How can I include @Annotations in JavaDoc?

Question

I would like to document some properties of classes and methods in JavaDoc and be able to load these information at runtime. Therefore I thought it might be convenient to write a custom annotation and annotate all necessary files and methods with this annotation. With this annotation, I could load these information at runtime.

Here's a hypothetic code snippet to demonstrate my use case:

public class ImportantClass {
  @DetailedDescription(description="originated from data source XYZ")
  public void importantMethod() {
    // snip
  }
}

The String "originated from data source XYZ" should be displayed in the JavaDoc and be readable via reflections or something similar. My problem is that the JavaDoc does not contain annotation information.

Is it possible to configure the JavaDoc task (preferrably with Maven) to include annotation information?

Clarification: I'm not interested in doclets (~javadoc annotations) as they are not readable at runtime.

score 12 · Accepted Answer · edited May 23 '17 at 12:32

12

I finally found a nice solution without duplication. Use the @Documented annotation on the annotation interface (DetailedDescription in this case) and all instances of this annotation are documented in the JavaDoc. See this question:

Is there a way to get the javadoc tool to document annotations?

edited May 23 '17 at 12:32

Community

1
1

answered Dec 09 '13 at 15:26

guerda

23,388
27
97
146

score 4 · Answer 2 · answered Dec 03 '13 at 15:28

This is more of a comment than an answer, but it is long so I need this format

Why do you want an annotation for that? The Oracle documentation says that for this kind of use, you should use both a javadoc tag and an annotation. From the link I provided:

If you need to affect both program semantics and documentation, you probably need both an annotation and a tag. For example, our guidelines now recommend using the @Deprecated annotation for alerting the compiler warning and the @deprecated tag for the comment text

Thank you for the hint. I'd like to keep the information in one place only, but it seems not possible. — guerda, Dec 04 '13 at 14:51

score -1 · Answer 3 · answered Dec 03 '13 at 15:53

-1

Use javadocs, it provides exactly what you are trying to achieve. Annotations provide metadata at the code level, and are meant to play role in the behaviour of your app. Should not be used for documentation.

answered Dec 03 '13 at 15:53

gyorgyabraham

2,550
1
28
46

One case, the one bringing me to this question, is to have the javadoc include "relevant" metadata, in my case JAX-RS annotations, to avoid duplication. – Mirvnillith Oct 08 '14 at 12:20

How can I include @Annotations in JavaDoc?

3 Answers3