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.

2 files changed, 14 insertions, 3 deletions

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 5aaf31247b4..9b900e63099 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -333,6 +333,11 @@ and equal-looking objects are considered the same key.
 (make-hash-table :test 'contents-hash)
 @end example
 
+Lisp programs should @emph{not} rely on hash codes being preserved
+between Emacs sessions, as the implementation of the hash functions
+uses some details of the object storage that can change between
+sessions and between different architectures.
+
 @node Other Hash
 @section Other Hash Table Functions
 
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));