[Python-Dev] New Pythondoc by effbot (original) (raw)

Georg Brandl g.brandl-nospam at gmx.net
Sun Jan 22 08:24:09 CET 2006

Guido van Rossum wrote:

On 1/21/06, Terry Reedy <tjreedy at udel.edu> wrote:

On this page, 8 of 30 entries have a 'new in' comment. For anyone with no interest in the past, these constitute noise. I wonder if for 3.0, the timer can be reset and the docs start clean again. To keep them backwards compatible, they would also have to be littered with 'changed in 3.0' and 'deleted in 3.0' entries. Better, I think, to refer people to the last 2.x docs and a separate 2.x/3.0 changes doc. (That has nothing to do with Fredrik's efforts of course -- he's just faithfully copying the annotations from the existing docs.) If Python 3.0 is indeed the major incompatible release that we currently expect it will be, I agree that "new in 3.0" and "new in 2.x" annotations make little sense, since so much will be "new in 3.0" (or "deleted in 3.0"). It's probably better to have a separate document explaining the differences between 2.x and 3.0. For the 2.x line, however (and again post-3.0) I think the "new in X" annotations are important -- lots of people have to deal with different Python versions, and it's a lot easier to depend on "new in X" notations than to manually compare two or more versions of the docs. (Although you still need to do thorough testing -- like the rest of the docs, these annotations can't be 100% perfect.)

As far as noise goes, "new in X" is minor compared to all the stuff that's documented that the average user never needs... :-)

And, of course, the "new in 2.x" could be formatted less space-consuming, perhaps to the right of the method name.

Georg

More information about the Python-Dev mailing list