Annotations complement javadoc tags

Question

Why is it said that Annotations complement javadoc tags?

Answer 1

One possible reason is that the use of annotations can overlap with that of Javadoc tags.

The best example of course is the @deprecated Javadoc tag and the @Deprecated annotation, which both indicate the same thing.

Both annotations and Javadoc tags provide metadata about code elements.

Answer 2

Annotations are code and will be represented at the byte code level. Javadoc tags are documentation level artifacts and are meta-data for the javadoc processor.

If retention level of the annotation class is runtime, you can reflect over the class and access the annotation; no such possibility exists for the javadoc tag (unless you have access to source files and are parsing them).

So, in a very narrow sense (e.g. a javadoc processor that does bytecode processing, such as generating code) the tags can be considered "complementary" [sic] to annotations, but that's about it.

Overall, its a bad meme to carry around in your head as it really doesn't inform the true distinction between these two entirely different constructs.