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

[Chris Hegarty]

Hamlin,

> On 14 Mar 2017, at 08:21, Hamlin Li <huaming.li at oracle.com> wrote:
> 
> 
> On 2017/3/14 15:46, Hamlin Li wrote:
>> Hi Martin,
>> 
>> 
>> On 2017/3/14 15:06, Martin Buchholz wrote:
>>> I wouldn't put a blank line between javadoc tags.
>> Will fix it.
> Hi Martin,
> 
> Just update webrev in place to remove blank lines, webrev still at http://cr.openjdk.java.net/~mli/8176563/webrev.00/

I agree with Martin, I don’t think that '@since 9’ should be added to 
overrides of existing methods in subclasses, e.g. j.l.r.Method::setAccessible
is not “new” in 9.

Also, if a type is new in 9, then it is not necessary to add explicit
‘@since 9’ to every method, since there will be ‘@since 9’ at the
class description level.

-Chris.

> Thank you
> -Hamlin
>>> 
>>> I'm not sure whether @since is justified for new specialized implementations like ArrayDeque.removeAll.  It is somewhat misleading to add the @since because that method has worked just fine in past releases with no substantive spec change.
>>> 
>>> Hmmmm....
>>> The most important use case for @since is for developers who need to decide whether they can afford to use an API when targeting older platforms.  For this reason ... I think using @since for pre-existing inherited methods is a mistake (implementation detail).
>> Thank you. I'm expecting your comments, because seems either ways make sense, I'd like to discuss it in open alias.
>> Please check below information (especially the *red/bold* sentence) at http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html:
>> "
>> @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.
>> 
>> "
>> 
>> Thank you
>> -Hamlin
>>> 
>>> I don't remember which way I went 10 years ago - you might investigate.
>>> 
>>> On Mon, Mar 13, 2017 at 11:40 PM, Hamlin Li <huaming.li at oracle.com <mailto:huaming.li at oracle.com>> wrote:
>>> 
>>>    Would you please review the below patch?
>>> 
>>>    bug: https://bugs.openjdk.java.net/browse/JDK-8176563
>>>    <https://bugs.openjdk.java.net/browse/JDK-8176563>
>>> 
>>>    webrev: http://cr.openjdk.java.net/~mli/8176563/webrev.00/
>>>    <http://cr.openjdk.java.net/%7Emli/8176563/webrev.00/>
>>> 
>>> 
>>>    Thank you
>>> 
>>>    -Hamlin
>>> 
>>> 
>> 
>