commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [math] Annotations
Date Tue, 11 Feb 2014 04:01:53 GMT
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. 

> On 10 February 2014 23:01, Phil Steitz <> 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 (
>>> 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:
>>> 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:
>> For additional commands, e-mail:
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:
> .

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message