master c23a49d256: Improve sxhash-equal documentation

[Lars Ingebrigtsen]

branch: master
commit c23a49d256771739d78eca1f371f69c46979d90c
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Improve sxhash-equal documentation
    
    * doc/lispref/hash.texi (Defining Hash): Explain more about what
    sxhash-equal is for and what the caveats are.
    * src/fns.c (Fsxhash_eql, Fsxhash_equal): Clarify doc string.
---
 doc/lispref/hash.texi | 10 +++++++---
 src/fns.c             |  6 ++++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index a566d89824..6264945521 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -289,9 +289,13 @@ If two objects @var{obj1} and @var{obj2} are @code{equal}, 
then
 are the same integer.
 
 If the two objects are not @code{equal}, the values returned by
-@code{sxhash-equal} are usually different, but not always; once in a
-rare while, by luck, you will encounter two distinct-looking objects
-that give the same result from @code{sxhash-equal}.
+@code{sxhash-equal} are usually different, but not always.
+@code{sxhash-equal} is designed to be reasonably fast (since it's used
+for indexing hash tables) so it won't recurse deeply into nested
+structures.  In addition; once in a rare while, by luck, you will
+encounter two distinct-looking simple objects that give the same
+result from @code{sxhash-equal}.  So you can't, in general, use
+@code{sxhash-equal} to check whether an object has changed.
 
 @b{Common Lisp note:} In Common Lisp a similar function is called
 @code{sxhash}.  Emacs provides this name as a compatibility alias for
diff --git a/src/fns.c b/src/fns.c
index 6be6b6d616..7553a09446 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -4923,7 +4923,8 @@ Hash codes are not guaranteed to be preserved across 
Emacs sessions.  */)
 
 DEFUN ("sxhash-eql", Fsxhash_eql, Ssxhash_eql, 1, 1, 0,
        doc: /* Return an integer hash code for OBJ suitable for `eql'.
-If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)).
+If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)), but the opposite
+isn't necessarily true.
 
 Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
   (Lisp_Object obj)
@@ -4933,7 +4934,8 @@ Hash codes are not guaranteed to be preserved across 
Emacs sessions.  */)
 
 DEFUN ("sxhash-equal", Fsxhash_equal, Ssxhash_equal, 1, 1, 0,
        doc: /* Return an integer hash code for OBJ suitable for `equal'.
-If (equal A B), then (= (sxhash-equal A) (sxhash-equal B)).
+If (equal A B), then (= (sxhash-equal A) (sxhash-equal B)), but the
+opposite isn't necessarily true.
 
 Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
   (Lisp_Object obj)