From amk at amk.ca Sat Oct 4 03:16:04 2008 From: amk at amk.ca (A.M. Kuchling) Date: Fri, 3 Oct 2008 21:16:04 -0400 Subject: [Doc-SIG] dict.update docstring Message-ID: <20081004011604.GA21554@amk.local> 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 From aahz at pythoncraft.com Sat Oct 4 05:23:21 2008 From: aahz at pythoncraft.com (Aahz) Date: Fri, 3 Oct 2008 20:23:21 -0700 Subject: [Doc-SIG] dict.update docstring In-Reply-To: <20081004011604.GA21554@amk.local> References: <20081004011604.GA21554@amk.local> Message-ID: <20081004032320.GA10036@panix.com> 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 From g.brandl at gmx.net Sat Oct 4 10:18:39 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Sat, 04 Oct 2008 10:18:39 +0200 Subject: [Doc-SIG] dict.update docstring In-Reply-To: <20081004032320.GA10036@panix.com> References: <20081004011604.GA21554@amk.local> <20081004032320.GA10036@panix.com> Message-ID: 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. From robert.kern at gmail.com Mon Oct 6 21:12:50 2008 From: robert.kern at gmail.com (Robert Kern) Date: Mon, 06 Oct 2008 14:12:50 -0500 Subject: [Doc-SIG] "What's New" for all versions Message-ID: Whenever I have to look for when a feature was introduced, I go looking at the "What's New in Python 2.x" pages. Since the documentation for Python 2.x only contains the "What's New in Python 2.x" and none of the earlier parts, this becomes fairly tedious if I guess the version wrong. I'd really like to see all of the older "What's New" pages in the current Python version's documentation. There should be a single ToC page collating the ToCs for all of the "What's New" versions. I don't think it should replace the current ToC, but I think it should exist. I don't have time to work on this immediately, so I thought I would throw it out there to see if there's any interest. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco From blais at furius.ca Mon Oct 6 23:45:34 2008 From: blais at furius.ca (Martin Blais) Date: Mon, 06 Oct 2008 17:45:34 -0400 Subject: [Doc-SIG] "What's New" for all versions In-Reply-To: References: Message-ID: <1223329534.23331.1277854185@webmail.messagingengine.com> On Mon, 06 Oct 2008 14:12:50 -0500, "Robert Kern" said: > Whenever I have to look for when a feature was introduced, I go looking > at the > "What's New in Python 2.x" pages. Since the documentation for Python 2.x > only > contains the "What's New in Python 2.x" and none of the earlier parts, > this > becomes fairly tedious if I guess the version wrong. I'd really like to > see all > of the older "What's New" pages in the current Python version's > documentation. > There should be a single ToC page collating the ToCs for all of the > "What's New" > versions. I don't think it should replace the current ToC, but I think it > should > exist. > > I don't have time to work on this immediately, so I thought I would throw > it out > there to see if there's any interest. +1 on Robert's idea. I always end up bricolating some summary of the new changes for myself. It would be nice if it were just there. From g.brandl at gmx.net Wed Oct 8 20:58:00 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Wed, 08 Oct 2008 20:58:00 +0200 Subject: [Doc-SIG] "What's New" for all versions In-Reply-To: <1223329534.23331.1277854185@webmail.messagingengine.com> References: <1223329534.23331.1277854185@webmail.messagingengine.com> Message-ID: Martin Blais schrieb: > On Mon, 06 Oct 2008 14:12:50 -0500, "Robert Kern" > said: >> Whenever I have to look for when a feature was introduced, I go looking >> at the >> "What's New in Python 2.x" pages. Since the documentation for Python 2.x >> only >> contains the "What's New in Python 2.x" and none of the earlier parts, >> this >> becomes fairly tedious if I guess the version wrong. I'd really like to >> see all >> of the older "What's New" pages in the current Python version's >> documentation. >> There should be a single ToC page collating the ToCs for all of the >> "What's New" >> versions. I don't think it should replace the current ToC, but I think it >> should >> exist. >> >> I don't have time to work on this immediately, so I thought I would throw >> it out >> there to see if there's any interest. > > +1 on Robert's idea. > I always end up bricolating some summary of the new changes for myself. > It would be nice if it were just there. I've now changed the templates a bit to make all "What's new" documents accessible. This should be live on docs.python.org soon. 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. From robert.kern at gmail.com Sat Oct 11 02:05:09 2008 From: robert.kern at gmail.com (Robert Kern) Date: Fri, 10 Oct 2008 19:05:09 -0500 Subject: [Doc-SIG] "What's New" for all versions In-Reply-To: References: <1223329534.23331.1277854185@webmail.messagingengine.com> Message-ID: Georg Brandl wrote: > Martin Blais schrieb: >> On Mon, 06 Oct 2008 14:12:50 -0500, "Robert Kern" >> said: >>> Whenever I have to look for when a feature was introduced, I go looking >>> at the >>> "What's New in Python 2.x" pages. Since the documentation for Python 2.x >>> only >>> contains the "What's New in Python 2.x" and none of the earlier parts, >>> this >>> becomes fairly tedious if I guess the version wrong. I'd really like to >>> see all >>> of the older "What's New" pages in the current Python version's >>> documentation. >>> There should be a single ToC page collating the ToCs for all of the >>> "What's New" >>> versions. I don't think it should replace the current ToC, but I think it >>> should >>> exist. >>> >>> I don't have time to work on this immediately, so I thought I would throw >>> it out >>> there to see if there's any interest. >> +1 on Robert's idea. >> I always end up bricolating some summary of the new changes for myself. >> It would be nice if it were just there. > > I've now changed the templates a bit to make all "What's new" documents > accessible. This should be live on docs.python.org soon. That's better, thank you! Can you easily put the ToCs for all of the What's New pages onto that page? It would make skimming and searching even easier. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco From vinetouu at gmail.com Sun Oct 12 16:56:04 2008 From: vinetouu at gmail.com (John Doe) Date: Sun, 12 Oct 2008 16:56:04 +0200 Subject: [Doc-SIG] A minor slip while typing Message-ID: <1e64acb60810120756w5cb67d94qdcd098b40db74949@mail.gmail.com> Hello, please let me focus your attention to a little slip that was made while typing a code example in the Python 3.0 documentation. Please visit thislink and note the 3rd code example which starts like this: class C(object): def __init__(self): self._x = None This is probably a slip, because it should better be like this: class C(object): def __init__(self): self._x = None And since this is the only method with such coding style used, it's probably a slip. Please fix this if you have the time to do so. After all, it's not a very time-consuming thing to do. Thanks. -------------- next part -------------- An HTML attachment was scrubbed... URL: From g.brandl at gmx.net Fri Oct 17 00:20:39 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Thu, 16 Oct 2008 22:20:39 +0000 Subject: [Doc-SIG] "What's New" for all versions In-Reply-To: References: <1223329534.23331.1277854185@webmail.messagingengine.com> Message-ID: Robert Kern schrieb: > Georg Brandl wrote: >> Martin Blais schrieb: >>> On Mon, 06 Oct 2008 14:12:50 -0500, "Robert Kern" >>> said: >>>> Whenever I have to look for when a feature was introduced, I go looking >>>> at the >>>> "What's New in Python 2.x" pages. Since the documentation for Python 2.x >>>> only >>>> contains the "What's New in Python 2.x" and none of the earlier parts, >>>> this >>>> becomes fairly tedious if I guess the version wrong. I'd really like to >>>> see all >>>> of the older "What's New" pages in the current Python version's >>>> documentation. >>>> There should be a single ToC page collating the ToCs for all of the >>>> "What's New" >>>> versions. I don't think it should replace the current ToC, but I think it >>>> should >>>> exist. >>>> >>>> I don't have time to work on this immediately, so I thought I would throw >>>> it out >>>> there to see if there's any interest. >>> +1 on Robert's idea. >>> I always end up bricolating some summary of the new changes for myself. >>> It would be nice if it were just there. >> >> I've now changed the templates a bit to make all "What's new" documents >> accessible. This should be live on docs.python.org soon. > > That's better, thank you! Can you easily put the ToCs for all of the What's New > pages onto that page? It would make skimming and searching even easier. Done! Let me know if it works for you. 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.