documentation: mention the version in which a syntax construct was added
I wonder in which version the "except Foo as e" syntax was added (as opposed to "except Foo, e"). The documentations does not state this but I think it wasn't there in Python 2.4. I propose that such things are always mentioned in the documentation and formated so that you can easily find the version numbers. See how Mozilla marks such things (scroll down): https://developer.mozilla.org/en/DOM/range -panzi
Mathias Panzenböck <grosser.meister.morti@gmx.net> writes:
I wonder in which version the "except Foo as e" syntax was added (as opposed to "except Foo, e"). The documentations does not state this but I think it wasn't there in Python 2.4.
First in Python 3.0. Backported from there to Python 2.6. <URL:http://www.python.org/dev/peps/pep-3110/#compatibility>
I propose that such things are always mentioned in the documentation and formated so that you can easily find the version numbers.
Yes, that's a good proposal which is already known, and needs people to do the work of implementing and maintaining it. In the meantime, you have available the “What's New In Python” documents that accompany each version. -- \ “The surest way to corrupt a youth is to instruct him to hold | `\ in higher esteem those who think alike than those who think | _o__) differently.” —Friedrich Nietzsche, _The Dawn_, 1881 | Ben Finney
On Mon, Apr 18, 2011 at 2:00 PM, Mathias Panzenböck <grosser.meister.morti@gmx.net> wrote:
I wonder in which version the "except Foo as e" syntax was added (as opposed to "except Foo, e"). The documentations does not state this but I think it wasn't there in Python 2.4.
It was new in 2.6 to match the way 3.x does it (see PEP 3110).
I propose that such things are always mentioned in the documentation and formated so that you can easily find the version numbers.
That's actually a very good point. We're reasonably consistent about doing this in the library reference (via the "versionadded" and "versionchanged" tags), but it hasn't been done for the language reference. Fixing this would basically involve taking PEP 291, as well as the What's New documents for 2.6 and 2.7, and using that information to update the 2.7 language reference with appropriate annotations. The comparable change for 3.x would use the 3.1 and 3.2 What's New to update the 3.2 documentation (with a forward port to the 3.3 development line). Keeping it in mind for future changes that affect the language reference (such as PEP 380) is easy enough, but, as Ben noted, it will require someone to submit the requisite patches in order to retroactively add this information for past changes. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 4/18/2011 1:35 AM, Nick Coghlan wrote:
The comparable change for 3.x would use the 3.1 and 3.2 What's New to update the 3.2 documentation (with a forward port to the 3.3 development line).
Because of the moratorium, there should not have been any syntax changes for 3.2, and I do not remember any for 3.1. I agree that version tags should be used in the language reference as well as the library reference. -- Terry Jan Reedy
On 2011-04-18, at 07:35 , Nick Coghlan wrote:
On Mon, Apr 18, 2011 at 2:00 PM, Mathias Panzenböck <grosser.meister.morti@gmx.net> wrote:
I propose that such things are always mentioned in the documentation and formated so that you can easily find the version numbers.
That's actually a very good point. We're reasonably consistent about doing this in the library reference (via the "versionadded" and "versionchanged" tags), but it hasn't been done for the language reference. By the way, when we notice that the tag is missing in some places, what's the flow to fix it?
Today, I suggested using pkgutil.get_data to a colleague, and after a few checks I found out it was apparently added in 2.6 (it isn't available in my 2.5.5), but I didn't find that information marked up in the doc.
On 4/18/2011 1:40 PM, Masklinn wrote:
By the way, when we notice that the tag is missing in some places, what's the flow to fix it?
The tracker. Mark issue for 2.7, type documentation. If you know of multiple omissions, put them altogether.
Today, I suggested using pkgutil.get_data to a colleague, and after a few checks I found out it was apparently added in 2.6 (it isn't available in my 2.5.5), but I didn't find that information marked up in the doc.
Do mention (or quote from interpreter*) how you determine the info you request to be added. No many developers will want to go back and verify now just for 2.7 docs. * something like 2.5.5
import pkgutil; pkgutil.get_data ... Attribute error
2.6.x
import pkgutil; pkgutil.get_data <Method type ob at ...>
-- Terry Jan Reedy
participants (5)
-
Ben Finney -
Masklinn -
Mathias Panzenböck -
Nick Coghlan -
Terry Reedy