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

classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Hamlin Li
Would you please review the below patch?

bug: https://bugs.openjdk.java.net/browse/JDK-8176563

webrev: http://cr.openjdk.java.net/~mli/8176563/webrev.00/


Thank you

-Hamlin

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Martin Buchholz-3
I wouldn't put a blank line between javadoc tags.

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

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 <[hidden email]> wrote:

> Would you please review the below patch?
>
> bug: https://bugs.openjdk.java.net/browse/JDK-8176563
>
> webrev: http://cr.openjdk.java.net/~mli/8176563/webrev.00/
>
>
> Thank you
>
> -Hamlin
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Hamlin Li
Hi Martin,


On 2017/3/14 15:06, Martin Buchholz wrote:
> I wouldn't put a blank line between javadoc tags.
Will fix it.

>
> 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 <[hidden email]
> <mailto:[hidden email]>> 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
>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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 <[hidden email]
>> <mailto:[hidden email]>> 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
>>
>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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 <[hidden email]> 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 <[hidden email] <mailto:[hidden email]>> 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
>>>
>>>
>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

roger riggs
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.

Regards, Roger



On 3/14/17 5:00 AM, Chris Hegarty wrote:

> Hamlin,
>
>> On 14 Mar 2017, at 08:21, Hamlin Li <[hidden email]> 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 <[hidden email] <mailto:[hidden email]>> 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
>>>>
>>>>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Martin Buchholz-3
In reply to this post by Hamlin Li
On Tue, Mar 14, 2017 at 12:46 AM, Hamlin Li <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Daniel Fuchs
In reply to this post by Hamlin Li
Hi Hamlin,

I had the same remark than Roger & others about
ObjectInputFilter::checkInput.

The changes to LogManager are OK. How did I forget that @since?
Thanks for catching that!

Don't count me as Reviewer for the other java.util changes though.

best regards

-- daniel

On 14/03/2017 06:40, Hamlin Li wrote:

> Would you please review the below patch?
>
> bug: https://bugs.openjdk.java.net/browse/JDK-8176563
>
> webrev: http://cr.openjdk.java.net/~mli/8176563/webrev.00/
>
>
> Thank you
>
> -Hamlin
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Naoto Sato-2
In reply to this post by roger riggs
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 <[hidden email]> 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 <[hidden email]
>>>>> <mailto:[hidden email]>> 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
>>>>>
>>>>>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

David Holmes
In reply to this post by Martin Buchholz-3
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 <[hidden email]> 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
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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 <[hidden email]>
>> 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
>>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Hamlin Li
BTW, I did *remove* the unnecessary @since for
ObjectInputFilter.checkInput. :-)

Thank you

-Hamlin


On 2017/3/15 11:34, Hamlin Li wrote:

> 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 <[hidden email]>
>>> 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
>>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Daniel Fuchs
Hi Hamlin,

The new version looks good to me.
Maybe wait for review of the other interested parties ;-)

best regards,

-- daniel

On 15/03/2017 04:34, Hamlin Li wrote:

> BTW, I did *remove* the unnecessary @since for
> ObjectInputFilter.checkInput. :-)
>
> Thank you
>
> -Hamlin
>
>
> On 2017/3/15 11:34, Hamlin Li wrote:
>> 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 <[hidden email]>
>>>> 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
>>>>
>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Alan Bateman


On 15/03/2017 11:35, Daniel Fuchs wrote:
> Hi Hamlin,
>
> The new version looks good to me.
> Maybe wait for review of the other interested parties ;-)
>
This one looks right to me too.

-Alan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Hamlin Li
Hi,

Thank you for reviewing, as StackFramePermission was just removed in
JDK-8176815, so I remove the @since change for StackFramePermission, and
the rest code change is pushed.

Thank you

-Hamlin


On 2017/3/15 19:55, Alan Bateman wrote:

>
>
> On 15/03/2017 11:35, Daniel Fuchs wrote:
>> Hi Hamlin,
>>
>> The new version looks good to me.
>> Maybe wait for review of the other interested parties ;-)
>>
> This one looks right to me too.
>
> -Alan

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Mandy Chung

> On Mar 15, 2017, at 7:40 PM, Hamlin Li <[hidden email]> wrote:
>
> Hi,
>
> Thank you for reviewing, as StackFramePermission was just removed in JDK-8176815, so I remove the @since change for StackFramePermission, and the rest code change is pushed.
>

Thanks. The updated change looks fine.

Mandy
Loading...