"Jeroen De Dauw" jeroendedauw@gmail.com wrote in message news:AANLkTin9BKBSq2VKjDosbgs1e9CmF9yz1w8JniYSoOHW@mail.gmail.com...
Hey,
I think methods should have the @since annotation, as they can be added in a later version then the one the class was added in. This makes them non-redundant, so in no case should they be removed.
Cheers
-- Jeroen De Dauw
Don't panic. Don't be evil. 50 72 6F 67 72 61 6D 6D 69 6E 67 20 34 20 6C 69 66 65! --
On 15 August 2010 13:27, Niklas Laxström niklas.laxstrom@gmail.com wrote:
Hi,
The issue of how to use @since annotations recently came up in the code review. Those are essential for extension developers who want to target multiple MediaWiki versions with one codebase. I think we should come up a standard way to use those.
Without further talk, here are some issues we need to agree upon:
- Should every new class have a @since annotation
- Should every new function have a @since annotation
- Should every new method have a @since annotation
- Should other things have a @since annotation
- Should we remove @since annotations of methods at some point
I think 1) and 2) are uncontroversial. I think that in 3) having @since is redundant if the version is the same as in the @since for the class. For 4) I think the answer should be yes, if it can be used/accessed by other code. I also think that @since annotations for versions that are unsupported *can* be removed, but there is no harm to keep them around.
What are your opinions on these issues, or can you can come up with other issues related to @since that should be discussed? In short: we need to agree on a style, document it, stick to it and enforce it on the code review.
I hope to get a little more comments than my recent request for comments regarding the Message class naming issues :) There are more issues besides this one, for example Jeroen has a wishlist [1] of additions to coding conventions, but let's concentrate on just @since annotations in this thread.
[1] https://secure.wikimedia.org/wikipedia/mediawiki/wiki/User:Jeroen_De_Dauw/Co...
Since it won't be possible to tell the difference between "this block had a @since once but it has now been removed" and "no one's got around to putting a @since on this block yet", we should not create instances of the former case until we have eliminated the latter.
--HM