On Mon, Feb 10, 2014 at 11:01 PM, Phil Steitz <[email protected]> wrote:
> On 2/10/14, 5:14 PM, sebb 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. > > Ugh. Shades of the early Wittgenstein. Sorry, could not resist that ;) > > Seriously, I see the fact that it is written is natural language as > an *advantage* of javadoc. Having API documentation deteriorate > into a sequence of tags with externally defined "meanings" is not > appealing to me as either a contributor or a user. I know there may > be a happy medium to be found and I will not stand in the way here. > @What's #so #bad #about @annotations? @Especially! when! you! can! Yahoo! them! #on #the #interwebs?! G > > Phil > > > > 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] > > > > . > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- E-Mail: [email protected] | [email protected] Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/> Spring Batch in Action <http://www.manning.com/templier/> Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
