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@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
_______________________________________________
Doc-SIG maillist  -  Doc-SIG@[...].org
http://mail.python.org/mailman/listinfo/doc-sig