master 7a87ca09a73 2/4: Clarify permitted mutation in `maphash` documentation

[Mattias Engdegård]

branch: master
commit 7a87ca09a73d61b46bfcaca317095ce7545bd3f3
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Clarify permitted mutation in `maphash` documentation
    
    * doc/lispref/hash.texi (Hash Access):
    * src/fns.c (Fmaphash):
    Make it clear what the function passed as argument can do.  Until now
    these rules were unwritten, and are still unenforced.
---
 doc/lispref/hash.texi | 4 ++++
 src/fns.c             | 2 ++
 2 files changed, 6 insertions(+)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 3d3fe3e3be2..4270de664f1 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -206,6 +206,10 @@ This function calls @var{function} once for each of the 
associations in
 @var{table}.  The function @var{function} should accept two
 arguments---a @var{key} listed in @var{table}, and its associated
 @var{value}.  @code{maphash} returns @code{nil}.
+
+@var{function} is allowed to call @code{puthash} to set a new value
+for @var{key} and @code{remhash} to remove @var{key}, but should not
+add, remove or modify other associations in @var{table}.
 @end defun
 
 @node Defining Hash
diff --git a/src/fns.c b/src/fns.c
index 4531b237824..f862c1470c4 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -5651,6 +5651,8 @@ DEFUN ("remhash", Fremhash, Sremhash, 2, 2, 0,
 DEFUN ("maphash", Fmaphash, Smaphash, 2, 2, 0,
        doc: /* Call FUNCTION for all entries in hash table TABLE.
 FUNCTION is called with two arguments, KEY and VALUE.
+It should not alter TABLE in any way other than using `puthash' to
+set a new value for KEY, or `remhash' to remove KEY.
 `maphash' always returns nil.  */)
   (Lisp_Object function, Lisp_Object table)
 {