2

(Note: this is not the same question as to where to put the annotation or how to document the annotation itself)

When a piece of documented code is decorated with an annotation, this annotation usually shows up in the generated javadocs (for @Documented annotations). But what if I'd like to add some reasoning to the javadoc? (why is the annotation needed for this piece of code?)

There are two ways that come to my mind, but both are not ideal.

/**
 * My piece of code.<p>
 * Why @MyAnnotation is needed
 */
@MyAnnotation
public void pieceOfCode() {

This way the reason appears in the generated javadoc, but not together with the annotation itself.

/**
 * My piece of code.
 */
// Why @MyAnnotation is needed
@MyAnnotation
public void pieceOfCode() {

Like that the reason is very close to the annotation itself (less chance to get lost in a refactoring), but doesn't appear in the generated javadocs.

What I would like is something like the @param javadoc tag for annotations, e.g. @ann:

/**
 * My piece of code.
 * @ann MyAnnotation  There's a reason
 */
@MyAnnotation
public void pieceOfCode() {

For @Documented annotations I'd then expect the comment at the @ann tag to appear in the generated javadocs together with the mentioning of the annotation itself.

Is there a proper way do comment annotations? Are there any other javadoc tags that could help?

Community
  • 1
  • 1
pesche
  • 3,054
  • 4
  • 34
  • 35

1 Answers1

1

I think the annotation itself should be self describing and obvious as meta-data, so there should only little documentation itself.

Annotations, a form of metadata, provide data about a program that is not part of the program itself. Annotations have no direct effect on the operation of the code they annotate.

Annotations have a number of uses, among them:

  • Information for the compiler — Annotations can be used by the compiler to detect errors or suppress warnings.
  • Compile-time and deployment-time processing — Software tools can process annotation information to generate code, XML files, and so forth.
  • Runtime processing — Some annotations are available to be examined at runtime.

Source: http://docs.oracle.com/javase/tutorial/java/annotations/

If you take JUnit, Java EE or Spring for instance, the annotations are described in the tutorials and java docs itself.

are in my sense self-descriptive or are clarified in the respective java docs itself.

The annotation is linked, so you can jump in the javadoc page into the annotation itself. That should be sufficient in my opinion.

I could further suggest, to use @see <annotation> for the extra meaning. I don't think there is something similiar with @param. I looked always so far at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#orderoftags for javadoc, hence the is a specific order for javadoc tags.

cinhtau
  • 1,002
  • 8
  • 16
  • 2
    Usually the annotation is well known and doesn't need explanation. What I want to document is why a specific annotation was chosen. E.g. when a class is annotated with `@Singleton`, everybody knows what it does, but what often needs to be written down also is _why_ the class has to be a `@Singleton` – pesche Jul 07 '14 at 11:33
  • So far I can't think of a better solution then, that to write it in javadoc itself. You can format it reserved a separate section for this intent with

    e.g. Apparently there is no extra tag for the cause. :-(     – cinhtau Jul 07 '14 at 12:13
  • Well, yes. The annotations should be, and in my case, JUnit `@Parameter`, is, documented in the source code. Easy access with the link and no other ways. – WesternGun May 11 '18 at 06:31