[UPDATED] RFR: 8044740: Convert all JDK versions used in @since tag to 1.n[.n] in jdk repo

[Henry Jen]

On 06/09/2014 08:14 AM, mark.reinhold at oracle.com wrote:
> Henry -- Thanks for taking on this huge cleanup task!  A couple of
> comments below.
>
> 2014/6/4 3:52 -0700, henry.jen at oracle.com:
>> ...
>>
>> Regarding to whether we should keep JDK, the later convention is 1.#,
>> and as David pointed out the document also list @since that way, I think
>> we should settle on that.
>
> I agree.  A "JDK" prefix on every version number would be redundant.
>

Consider settled, thanks.

>> For other standards such as SAX or JCE, I propose to convert them to the
>> version of JDK those APIs are included. To retain that information, we
>> can introduce a custom tag, perhaps @standard or @conformingTo?
>
> These secondary version numbers aren't always for standards as such, and
> in some cases they no longer have any real meaning.  JCE, e.g., was a
> standlone technology which was folded into the JDK many releases ago and
> hasn't really had its own version number since.  So to do this right
> you'd need to figure out what's a "standard" and what's not, which could
> take a fair bit of time, and it's not worth introducing new custom tags
> if we aren't going to do it right.
>
> I suggest you just retain the secondary version numbers and list them
> after the primary, e.g.,
>
>   * @since 1.6, SAX 2.0

This webrev doesn't involve any changes on this proposal, just wants to 
start the discussion to figure what we should do.

I think as long as the first is the JDK version, and convention is 
established, i.e, developer knows how to read it, this is fine.

I am not sure if that extra information is worth to preserve or not, 
custom tag allows we retain the information in code, but not disclose 
them in javadoc until we are ready.

There are a couple tags I found in existing javadoc seems relevant, like 
@spec and @revised.

>
>> ...
>>
>> Some changes not obvious are simply remove tailing space, a (positive)
>> side effect of the tools I use so I kept them.
>
> I suggest you limit your patch only to change the @since tags.  That
> will make it easier to review and easier to comprehend later on.  The
> whitespace cleanup can be done separately.
>

I strip out those changes, so the updated webrev is essentially 
normalize JDK version format.

Since this is just change format, not actually change any version 
values, I think current review received is sufficient.

I will commit this to jdk9/dev 12:00PM 6/10 PDT with current reviewers 
unless explicit veto was received by then.

Cheers,
Henry