Re: maphash: improve docstring

[Stefan Monnier <monnier@iro.umontreal.ca>]

> 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