"Jeroen De Dauw" <[email protected]> wrote in message news:[email protected]... > 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 > * http://blog.bn2vs.com > * http://wiki.bn2vs.com > 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 <[email protected]> > 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: >> 1. Should every new class have a @since annotation >> 2. Should every new function have a @since annotation >> 3. Should every new method have a @since annotation >> 4. Should other things have a @since annotation >> 5. 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/Code_style
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 _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
