Re: maphash: improve docstring

[Paul Pogonyshev]

[I didn't receive the answer because I wasn't subscribed to the list,
 so the thread will be broken]

> > Docstring for `maphash' doesn't give any answer to the following
> > question: is the callback FUNCTION allowed to access the hash
> > table in read mode (I guess yes) and write mode?  About the
> > latter I have no idea without studying internal implementation.
>
> > E.g., is the following code going to work as a way to filter a
> > hash table?
>
> Yes, you are allowed to modify the table while iterating over it and the
> resulting behavior should be sane.
>
> And it should have the usual desired properties: The set of elements
> passed to the function is a superset of all the elements that aren't
> removed during the iteration, and a subset of all the elements that were
> present at the beginning or added during the loop.  IOW if an entry is
> untouched during the loop, then it will be passed (exactly once) to the
> function.  If an entry is added or removed during the loop, then maybe
> it will be passed to the function, but maybe not.  And if an entry is
> modified during the loop, then it will be passed to the function
> (exactly once) and the value passed will be the one that happens to be
> current when the function is called.
>
> More specifically, you're guaranteed when entering the function that the
> key you've received does currently exist in the table and is currently
> associated with the value you just received.

Could one expand documentation of `maphash' like this?  I'm not
sure it follows from what you wrote, but I understood it like
this:

    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.

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.

Paul