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. On Apr 21, 2016 4:54 PM, "Stuart Marks" <stuart.marks@oracle.com> wrote:

On 4/21/16 9:51 AM, Paul Benedict wrote:

...

Is there a requirement that the new "since" attribute on @j.l.Deprecated lead to an automatic JavaDoc @deprecated in the doc generation? It's a bona fide replacement, right?

I'm just curious because I think, if that's true, @j.l.Deprecated should mention this tool coordination in its own JavaDoc header.

I'm not sure what you mean by "since" in the annotation leading to an "automatic" javadoc tag.

But to clarify, the @Deprecated annotation and the @deprecated javadoc tag are complementary; neither is a replacement for the other. The annotation contains "since" and "forRemoval" information and ends up in memory at runtime, since it has runtime retention. The javadoc tag should have descriptive text that explains the rationale for deprecation, risks of using, preferred alternatives, etc.

It should be considered an error to have the annotation without the javadoc tag and vice-versa. Javac does some checking in this regard, but it only does the check in one direction! The tools should check both. See

https://bugs.openjdk.java.net/browse/JDK-8141234

Aside from that, if you think something needs to be clarified in the doc for the @Deprecated annotation, please suggest it. Now's the time.

s'marks

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