RFR: 8047722: @since tag cleanup in corba

[Stuart Marks]

On 6/30/14 8:17 AM, Henry Jen wrote:
> On 06/30/2014 12:18 AM, Alan Bateman wrote:
>> On 30/06/2014 02:30, Henry Jen wrote:
>>> On 06/20/2014 02:28 PM, Henry Jen wrote:
>>>> Please review a trivial webrev for jdk9/corba that do the same @since
>>>> tag normalization as in jdk9/jdk.
>>>>
>>>> http://cr.openjdk.java.net/~henryjen/jdk9/8047722/0/webrev/
>> There are bunch of @since JDK 1.0 and JDK 1.1.6 that you are changing to
>> 1.0 and 1.1.6. AFAIK, CORBA was added in 1.2 and I wonder if we should
>> fix this as part of this change.
>>
>
> Thanks for review. You are correct that CORBA was added in 1.2.
>
> My understadning to those 1.0 to 1.1.6 versions are for override methods, I
> guess the author is putting down the version of the origin.
>
> There are several cases where @since can be ambiguous without a common guideline,
>
> - An method was private or package access only made public, should @since denote
> the API availablity or the implementation?
>
> - APIs from classed was extracted into a super class or interface in a later
> version, what should be the @since?
>
> - Implementation of interface methods
>
> - Override methods
>
> Guess they are actually all the same question, does @since mean API availability
> or implementation?
>
> For prior, interface/override methods should not carry it's own since, for
> later, it should have @since as the owner class.

There are some strange cases here.

But the high order question is API vs implementation, and I think @since really 
is about API. However, I don't think @since should be inherited. For example, 
Collection was added in 1.2 and Queue (extends Collection) was added in 1.5. 
Queue has an add() method that's specified by Collection, but Queue.add() 
shouldn't have @since 1.2 on it, since Queue.add() didn't exist before 1.5.

On the other hand, the addition of an overriding method shouldn't cause @since 
to change, because the overridden method was available on that class at the 
point it was introduced even though it was inherited, not overridden.

I'd also say that when a private or package-access is made protected or public, 
it becomes visible in the API at that point, so @since should have the release 
at which it became visible, not when the implementation was introduced.

However, protected => public doesn't change the visibility, so that shouldn't 
cause @since to change. [1]

Pulling up a method into a superclass or superinterface (do we ever do this?) is 
like introducing an API into that class/interface, so @since should record when 
that happened.

I looked at src/share/classes/com/sun/corba/se/impl/io/IIOPInputStream.java and 
there are some odd cases here.

First, the class itself is a private implementation class in com.sun, so do we 
need to track @since tags for it?

Second, the class has a @since 1.1.6 tag which seems to conflict with the 
introduction of CORBA into 1.2. However, IIOPInputStream inherits from 
ObjectInputStream, which says "@since JDK1.1" so I'm not sure where 1.1.6 might 
have come from.

Third, the readObjectDelegate(), defaultReadObjectDelegate(), and 
enableResolveObjectDelegate() methods each have *two* @since tags, JDK1.1.6 and 
JDK1.1. Not sure where these would have come from, since ObjectInputStream has 
never had such methods.

Fourth, CORBA contains *copies* of old versions of some source files, such as 
ObjectStreamClass_1_3_1.java and IdentityHashTable.java (read the comments for 
why). Those files have @since tags apparently copied from the originals, 1.1 and 
even 1.0. If these were API classes I'd say that @since ought to have been 
adjusted to the actual release of introduction, but they're private 
implementation classes, so....

* * *

Anyway, it looks like all the 1.1.6 references occur in private implementation 
classes, so they won't be visible in javadoc. Even though these are arguably 
wrong it probably doesn't matter. Changing "JDK1.1" to "1.1" is probably OK. But 
maybe we just don't need to worry about fixing things like the presence of "1.1" 
in a package that was introduced until 1.2, or fixing duplicate @since tags, etc.

Aside from this, the additions and fixes in the public API files look fine to me.

s'marks


[1] 
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@since