[Doc-SIG] dict.update docstring

[A.M. Kuchling]

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!

--amk