bug#45178: buffer-hash docstring should explain difference to secure-hash

[Lars Ingebrigtsen <larsi@gnus.org>]

Stefan Kangas <stefan@marxist.se> writes:

> Severity: minor
>
> It is not clear to me when I would want to use:
>
>     (buffer-hash (current-buffer))
>
> instead of
>
>     (secure-hash 'sha1 (current-buffer))
>
> One obvious difference is that secure-hash respects narrowing, while
> buffer-hash doesn't.

I thought the buffer-hash doc string made the use case pretty clear:

----
This function is useful for comparing two buffers running in the same
Emacs, but is not guaranteed to return the same hash between different
Emacs versions.
----

The only use case for the function is to compare two buffers in the same
running Emacs image.  It shouldn't be used for anything else.

> First, I think we should add something about this to the docstring of
> `buffer-hash'.  Perhaps we should also mention it in the `secure-hash'
> docstring.

I think that would be pointing people in the wrong direction.
`secure-hash' is the right thing to use in 99% of the cases.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no