[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: maphash: improve docstring
From: |
Paul Pogonyshev |
Subject: |
Re: maphash: improve docstring |
Date: |
Sat, 2 Apr 2016 14:13:57 +0200 |
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 <address@hidden> 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
maphash-doc.diff
Description: Text document
- Re: maphash: improve docstring,
Paul Pogonyshev <=