How about the following patch?

Paul



* src/fns.c (Fmaphash): Add reference to the corresponding Info
  node to the docstring.

* doc/lispref/hash.texi (Hash Access): Expand documentation of
  'maphash' with detailed description of what happens if
  'function' modifies the 'table'.

On 30 March 2016 at 00:44, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>> Could one expand documentation of `maphash' like this?  I'm not sure
>> it follows from what you wrote, but I understood it like this:
>
> That looks right.
>
>>     Call FUNCTION for all entries in hash table TABLE.
>>     FUNCTION is called with two arguments, KEY and VALUE.
>>     `maphash' always returns nil.
>>     FUNCTION will usually just inspect its arguments, but may also
>>     alter TABLE and this will not cause `maphash' to malfunction.
>>     However, some effects are not fully defined, see below.
>>     If FUNCTION adds an entry to TABLE, it may or may not be called
>>     with the added key/value pair.
>>     If FUNCTION changes value already associated with a key and it
>>     has not been called with that key yet, it will be called with key
>>     and the new value during the iteration later.  Otherwise it will
>>     not be called for that key again.
>>     If FUNCTION removes a key and it has not been called with it yet,
>>     it will not be called for the removed key in the future either.
>>     Note that if FUNCTION removes or changes value only for KEY it is
>>     called with, the behavior is completely defined.
>
> Yes.  I think we can come up with something more concise (by splitting
> the description of which keys will be called, from the description of
> which value is passed), but haven't been very successful at it either.
>
>> Another option is to add this (probably with more explanation) to
>> the manual and add just a sentence to the tune of "see manual for
>> details" to the docstring.
>
> Sure,
>
>
>         Stefan