Improve documentation of hash-code functions

* src/fns.c (Fsxhash_eq, Fsxhash_eql, Fsxhash_equal):
* doc/lispref/hash.texi (Defining Hash): Warn against assuming
that sxhash returns consistent results.

1 files changed, 9 insertions, 3 deletions

diff --git a/src/fns.c b/src/fns.c
index eaa2c07fbe4..fd0c7fc71a0 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -4695,7 +4695,9 @@ sxhash (Lisp_Object obj, int depth)
 
 DEFUN ("sxhash-eq", Fsxhash_eq, Ssxhash_eq, 1, 1, 0,
        doc: /* Return an integer hash code for OBJ suitable for `eq'.
-If (eq A B), then (= (sxhash-eq A) (sxhash-eq B)).  */)
+If (eq A B), then (= (sxhash-eq A) (sxhash-eq B)).
+
+Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
   (Lisp_Object obj)
 {
   return make_fixnum (hashfn_eq (NULL, obj));
@@ -4703,7 +4705,9 @@ If (eq A B), then (= (sxhash-eq A) (sxhash-eq B)).  */)
 
 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)).
+
+Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
   (Lisp_Object obj)
 {
   return make_fixnum (hashfn_eql (NULL, obj));
@@ -4711,7 +4715,9 @@ If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)).  */)
 
 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)).
+
+Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
   (Lisp_Object obj)
 {
   return make_fixnum (hashfn_equal (NULL, obj));