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