Conversely, adding an annotation would require the addition of features to external tool sets and boilerplate to make it work seamlessly, rather than just being a nuisance. It's definitely a win some, lose some situation from the sounds of it.
-Chris On Mon, Feb 10, 2014 at 6:14 PM, sebb <[email protected]> wrote: > The advantage of annotations over Javadoc is that the meaning of each > annotation is precisely defined. > > Javadoc is mainly written in natural language. > This much harder to pin down precisely (and harder to parse), unless > one defines a convention for how to express the various > characteristics of the code that one wishes to document. In which case > one might as well use the appropriate annotation. > > On 10 February 2014 23:01, Phil Steitz <[email protected]> wrote: > > On 2/10/14, 1:16 AM, Thomas Neidhart wrote: > >> Hi, > >> > >> this is an issue I was thinking about for some time now, and it is quite > >> some recurrent theme that we face in Commons. > >> > >> Considering our release practice, it is actually quite hard to come up > with > >> new features as the API is more or less fixed once it has been included. > >> Ideally, this could or should be handled with alpha/beta releases were > we > >> gather feedback on a new API, but due to limited resources this does not > >> seem feasible. From experience in Math we also see that when we want to > >> extend an existing API for further uses, it is sometimes impossible to > be > >> backwards compatible simply because the original API did not foresee > such > >> things, which is quite normal I guess. > >> > >> Thus, I would like to discuss another approach. Add certain annotations > to > >> the code that clearly mark the mark the current state of a class/type > and > >> which allows us to break compatibility for such classes even in minor > >> releases. > >> > >> As a first step I would foresee the following annotations: > >> > >> * Internal: Only for internal use, no guarantee about BC or may even be > >> removed without warning > >> * Beta: New API, may be changed in minor releases after gathering > feedback > >> from the community > >> > >> Additionally, I would like to introduce also the annotations from the > jcip ( > >> jcip.net). I do not know if we can add them as dependency, but we could > >> also add them ourselves. IMO this would be of great benefit to our > users if > >> it is clear if a certain class is Immutable, ThreadSafe or Not and one > does > >> not have to analyze the source code to assert him/herself. > >> > >> I created a ticket for this, and started with two annotations so far: > >> > >> https://issues.apache.org/jira/browse/MATH-1098 > >> > >> So what do you think about that? > > > > I agree with the problem statement; but I am not sure annotations > > are the best or only solution. I agree with Chris that explicit > > class / method or package javadoc is a good way to communicate what > > we need to say and it has the advantage of being plain English, full > > sentences not demanding that one learn a special vocabulary or > > figure out how detached definitions apply in the context of the API. > > > > IIRC, we have talked before about handling the biggest problem - > > "Internal" by just doing it explicitly - i.e., o.a.c.m.internal. > > That is not as ridiculous as it sounds. The only reason we *need* > > to expose internal stuff is so it can be used outside the package > > where it is defined. Therefore, .internal adds no import bloat. It > > is also obvious and simple. > > > > Regarding "beta" - it seems that annotation at the class / method > > level for this might end in a maintenance morass and if / when we > > ever did build integration, all kinds of funny corner cases / breaks > > might emerger. And for what gain, exactly, beyond just noting in > > the javadoc and release notes that something is beta and subject to > > change. Just slapping an annotation on a class or method does not > > absolve us of the responsibility to explain why an API is unstable / > > where it is going. > > > > The other stuff - threadsafety, immutability, etc, seem to me to be > > asking for maintenance pain and also harder than you might think to > > precisely define and consistently get right. Better, IMHO to > > explicitly cover this stuff, when relevant, in plain English javadoc > > in the context of the API. > > > > All that said, could be I am just being old-fashioned here and > > annotations will make the world much easier for us and users, so if > > others agree this is the way to go, I will try my best to help. I > > definitely want to help attack the "internal" and "beta" problems > > somehow, so thanks, Thomas, for bringing this to the fore. > > > > Phil > >> > >> Thomas > >> > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- Chris
