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. 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]
