[docs] [issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate
report at bugs.python.org
Fri Feb 19 12:21:05 EST 2016
Tony R. added the comment:
> Part of the problem is getting the granularity right. The initial intent was
> that 'version*' were annotations for the enclosing object (function, class,
> method, etc.). If we want to have something more granular (parameter
> added / deprecated / whatever), we should have distinct markup for that.
> That could look something like:
> .. parameteradded:: alternate 3.6
> Further explanation goes here.
> It's helpful to think of these annotations as pronouns; the antecedent
> needs to be clear before they can be interpreted correctly.
Isn’t language fun?!?! *insane smile* 8)
> It sounds
> like that needs to be clarified in the documentation, and possibly
> provision added for a more fine-grained form of annotation.
Okay. I can participate in the discussion of that, if it would help...but adding a completely new annotation type is outside my current ability to contribute.
> > Well then, if this is the sort of place where the status quo is sacred,
> > then there is nothing more to discuss.
> That wasn't my intention when quoting the old documenting guide, it was just
> to show what the intent was (and still is), and that I didn't just invent it.
Your intent was clear to me! I did not mean to say that you -- or anyone -- just invented it.
I only know that mature projects (like Python) tend to hold more strongly to the status quo, and that I was advocating a change that was probably going to be an uphill battle to convince others as worthwhile.
> That's a nice strawman -- we all feel semantic markup is important, and we
> are talking about nothing but semantic markup here. We're just discussing
> the interpretation of one aspect of the semantics.
It was not my wish to set up a strawman. (I have no formal training in logic, anyways; I’d probably screw it up if I deliberately tried!)
The reason I was stressing semantic markup is because I anticipated resistance from the mindset of “Ugh, I don’t want to deal with this tedious crap!” I wanted to emphasize semantic markup as something valuable -- worth making an effort for, even if it might appear tedious or trivial at first glance.
That said, I think it’s time for me to bow out of this conversation. I’ve never made a successful contribution to any part of Python, including the documentation. There was some talk of updating the devguide or adding new annotations, so I hope that something good comes out of that! But the issue patch is where my comfort level is right now, and it appears that it’s a no-go.
Thank you for your time, your consideration, and the discussion!
Python tracker <report at bugs.python.org>
More information about the docs