@Deprecated(since) and Javadoc
stuart.marks at oracle.com
Fri Apr 22 02:02:21 UTC 2016
On 4/21/16 4:51 PM, Paul Benedict wrote:
> Well, my point was that it becomes redundant coding to specify both the
> annotation and the Javadoc tag. It would just seem better, in my opinion, if
> doing a @j.l.Deprecated(since="9") triggered whatever output is necessary
> during doc generation. It doesn't make sense to me to require both. The
> language annotation, with the new attribute, is now expressive enough for
> generation needs. Asking the developer to do both is wasteful effort, I think.
If you want to deprecate something and not provide any documentation about why
it was deprecated or what it should be replaced with, then the @Deprecated
annotation will be sufficient. Javadoc will place a boldface heading
into the javadoc output. (This has been true in JDK 8 and earlier, and it has
nothing to do with the new "since" element in the @Deprecated annotation.)
If you want documentation about the deprecation (rationale and replacement) then
you do need to add a @deprecated javadoc tag, as redundant as that may seem.
There's no place to put such documentation in the @Deprecated annotation.
More information about the core-libs-dev