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

[Naoto Sato]

On 3/14/17 7:53 AM, Roger Riggs wrote:
> Hi,
>
> - The @since in ObjectInputFilter.checkInput is unnecessary; the class
> has @since 9
>
> - java.util.Properties.replace @since seems unnecessary because it will
> not be seen.
>   The @hidden is a bit odd too but that has its own explaination (btw,
> it is the only one in the jdk).
>
> - I agree about not needing @since on overrides of existing methods.
>    Even for toString() though in some cases the javadoc now has useful
> info about the toString contents.

I just took a look at Locale.java, and had the same opinion. No need for 
@since for toString().

Naoto

>
> Regards, Roger
>
>
>
> On 3/14/17 5:00 AM, Chris Hegarty wrote:
>> 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
>>>>>
>>>>>
>