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

[Stefan Kangas]

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.  But it's not clear to me why I can't just use
save-restrictions+widen instead.  The Elisp manual says: "It should be
somewhat more efficient on larger buffers than ‘secure-hash’ is, and
should not allocate more memory."

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.

Second, is the difference all that important?  If so, perhaps we should
look over our uses of `md5', `sha1' and `secure-hash' in our code-base
to ensure we use the more efficient version where applicable.  (For
example in savehist.el and desktop.el.)