On 4/21/2016 7:02 PM, Stuart Marks wrote:
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
*Deprecated.*
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.
The distinct java.lang.Deprecated annotation type separate from the
@deprecated javadoc tag was a deliberate design decision made back in
JDK 5. Just as @throws tags and the method throws clauses are
complementary, so are the annotation and javadoc tag associated with
deprecation. It would be awkward to perform javadoc processing on a
string in an annotation.
Cheers,
-Joe
