Hamlin, > On 14 Mar 2017, at 08:21, Hamlin Li <huaming...@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...@oracle.com >>> <mailto:huaming...@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 >>> >>> >> >
