dict.update docstring

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: 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 ([hidden email])           <*>         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  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: dict.update docstring

Georg Brandl-2
Aahz schrieb:

> 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.

I agree.

Georg

--
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig