[Doc-SIG] dict.update docstring
Aahz
aahz at pythoncraft.com
Sat Oct 4 05:23:21 CEST 2008
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
More information about the Doc-SIG
mailing list