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

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

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

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

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

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

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

[David Holmes]

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

Re: 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  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.

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

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

[Daniel Fuchs]

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

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

[Martin Buchholz]

On Tue, Mar 14, 2017 at 12:46 AM, Hamlin Li  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

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

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

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

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.


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

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.


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

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

[Martin Buchholz]

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.

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