[Doc-SIG] dict.update docstring

[Georg Brandl]

Aahz schrieb:
> On Fri, Oct 03, 2008, A.M. Kuchling wrote:
>>
>> I've been looking at the docstrings of the built-in types, and I found
>> the docstring for dict.update() really hard to understand.
>> 
>> | update(...)
>> |  D.update(E, **F) -> None.  Update D from E and F: for k in E: D[k] = E[k]
>> |  (if E has keys else: for (k, v) in E: D[k] = v) then: for k in F: D[k] = F[k]
>> 
>> The parenthetical 'if E has keys' is the most unreadable part; it's
>> actually referring to the keys() method.
>> 
>> My proposed rewrite (as formatted by pydoc):
>> 
>>  |  update(...)
>>  |      D.update(E, **F) -> None.  Update D from dict/iterable E and F.
>>  |      If E has a .keys() method, does:     for k in E: D[k] = E[k]
>>  |      If E lacks .keys() method, does:     for (k, v) in E: D[k] = v
>>  |      In either case, this is followed by: for k in F: D[k] = F[k]
>> 
>> Does this seem clear, or should it be expanded more?  dict.update is
>> pretty complicated!
> 
> The docstring should only be a reminder, not a complete set of docs;
> given a person who once understood what d.update() does and how it
> works, your proposed rewrite seems to me more than sufficient.

I agree.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.