RFR of JDK-8176563: @since value errors in apis of java.base/java.logging module

[Hamlin Li]

Hi everyone,

Thanks a lot for the patient review and comments, I think you're right 
to remove @since when overriding methods, I will also adjust the tool to 
take this into account.

I have updated as everyone suggested, new webrev is at : 
http://cr.openjdk.java.net/~mli/8176563/webrev.01/


Thank you

-Hamlin


On 2017/3/15 8:39, David Holmes wrote:
> Hamlin,
>
> I have to agree with Martin here. These changes seem very misguided in 
> places. Only NEW types or new type members should be flagged with @since.
>
> For example, adding "@since 9" to 
> java.lang.reflect.Field.setAccessible is just WRONG!
>
> David
>
> On 15/03/2017 2:06 AM, Martin Buchholz wrote:
>> On Tue, Mar 14, 2017 at 12:46 AM, Hamlin Li <huaming.li at oracle.com> 
>> wrote:
>>
>>>
>>> @since *since-text*
>>>
>>> Introduced in JDK 1.1
>>>
>>> Adds a *Since* heading with the specified since-text value to the
>>> generated documentation. The text has no special internal structure. 
>>> This
>>> tag is valid in any documentation comment: overview, package, class,
>>> interface, constructor, method, or field. *This tag means that this
>>> change or feature has existed since the software release specified 
>>> by the*
>>>  *since-text* *value*, for example: @since 1.5.
>>>
>>> For Java platform source code, the @since tag indicates the version of
>>> the Java platform API specification, which is not necessarily when the
>>> source code was added to the reference implementation. Multiple 
>>> @since tags
>>> are allowed and are treated like multiple @author tags. You could use
>>> multiple tags when the program element is used by more than one API.
>>>
>> Instead of focusing on the *red text*, I read
>>
>>
>> """For Java platform source code, the @since tag indicates the 
>> version of
>> the Java platform API specification"""
>>
>>
>> as being all about API, not implementation.  There is no @modifiedIn or
>> @optimizedIn tag
>>