emacs-30 fc7581ae2ee: ; Fix documentation of secure-hash functions

[Eli Zaretskii]

branch: emacs-30
commit fc7581ae2ee9db1e3189b76c66be9cd13f72f004
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Fix documentation of secure-hash functions
    
    * src/fns.c (Fsecure_hash):
    * doc/lispref/text.texi (Checksum/Hash):
    * lisp/subr.el (sha1): Fix documentation wrt to the number of
    bytes 'secure-hash' and its variants return when BINARY is
    non-nil.  Reported by Pip Cet <pipcet@protonmail.com>.
---
 doc/lispref/text.texi | 14 +++++++-------
 lisp/subr.el          |  2 +-
 src/fns.c             |  4 +++-
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 196fe89a092..278b53d7f65 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4992,22 +4992,22 @@ of the returned string depends on @var{algorithm}:
 
 @itemize
 @item
-For @code{md5}: 32 characters (32 bytes if @var{binary} is
+For @code{md5}: 32 characters (16 bytes if @var{binary} is
 non-@code{nil}).
 @item
-For @code{sha1}: 40 characters (40 bytes if @var{binary} is
+For @code{sha1}: 40 characters (20 bytes if @var{binary} is
 non-@code{nil}).
 @item
-For @code{sha224}: 56 characters (56 bytes if @var{binary} is
+For @code{sha224}: 56 characters (28 bytes if @var{binary} is
 non-@code{nil}).
 @item
-For @code{sha256}: 64 characters (64 bytes if @var{binary} is
+For @code{sha256}: 64 characters (32 bytes if @var{binary} is
 non-@code{nil}).
 @item
-For @code{sha384}: 96 characters (96 bytes if @var{binary} is
+For @code{sha384}: 96 characters (48 bytes if @var{binary} is
 non-@code{nil}).
 @item
-For @code{sha512}: 128 characters (128 bytes if @var{binary} is
+For @code{sha512}: 128 characters (64 bytes if @var{binary} is
 non-@code{nil}).
 @end itemize
 
@@ -5062,7 +5062,7 @@ This function is equivalent to calling @code{secure-hash} 
like this:
 @end lisp
 
 It returns a 40-character string if @var{binary} is @code{nil}, or a
-40-byte unibyte string otherwise.
+20-byte unibyte string otherwise.
 @end defun
 
 @node Suspicious Text
diff --git a/lisp/subr.el b/lisp/subr.el
index a8e3df14cd3..28ba30f584e 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -4481,7 +4481,7 @@ Otherwise, return nil."
   "Return the SHA-1 (Secure Hash Algorithm) of an OBJECT.
 OBJECT is either a string or a buffer.  Optional arguments START and
 END are character positions specifying which portion of OBJECT for
-computing the hash.  If BINARY is non-nil, return a 40-byte unibyte
+computing the hash.  If BINARY is non-nil, return a 20-byte unibyte
 string; otherwise return a 40-character string.
 
 Note that SHA-1 is not collision resistant and should not be used
diff --git a/src/fns.c b/src/fns.c
index cb3e25811ea..6133c20573a 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -6402,7 +6402,9 @@ whole OBJECT.
 
 The full list of algorithms can be obtained with `secure-hash-algorithms'.
 
-If BINARY is non-nil, returns a string in binary form.
+If BINARY is non-nil, returns a string in binary form.  In this case,
+the function returns a unibyte string whose length is half the number
+of characters it returns when BINARY is nil.
 
 Note that MD5 and SHA-1 are not collision resistant and should not be
 used for anything security-related.  For these applications, use one