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

[Hamlin Li]

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/

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
>>
>>
>