From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 19 Aug 2024 14:51:50 +0000 (+0300)
Subject: ; Fix documentation of secure-hash functions
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=5cd789d09bbe3b46960507703c91c279e55d7e7d;p=emacs.git

; 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>.

(cherry picked from commit fc7581ae2ee9db1e3189b76c66be9cd13f72f004)
---

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 460d3df6f0c..03b2c3b2b6d 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -5000,22 +5000,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
 
@@ -5070,7 +5070,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 fae9ff27a09..36489a07e60 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -4096,7 +4096,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 1b672c53e61..7c0416f84ad 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -6419,7 +6419,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