[Doc-SIG] dict.update docstring

[Aahz]

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.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"...if I were on life-support, I'd rather have it run by a Gameboy than a
Windows box."  --Cliff Wells, comp.lang.python, 3/13/2002