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 ([EMAIL PROTECTED]) <*> 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@python.org http://mail.python.org/mailman/listinfo/doc-sig
