RFR: 8047722: @since tag cleanup in corba
stuart.marks at oracle.com
Wed Jul 2 00:31:38 UTC 2014
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.
>> 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. 
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
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.
More information about the core-libs-dev