RFR of JDK-8176563: @since value errors in apis of java.base/java.logging module
huaming.li at oracle.com
Tue Mar 14 07:46:42 UTC 2017
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.
> 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
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.
> 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
> webrev: http://cr.openjdk.java.net/~mli/8176563/webrev.00/
> Thank you
More information about the core-libs-dev