4

What is the recommended place to put JavaDoc for a method with an annotation? Before or after the annotation?

@Test
/**
 * My doc
 */
public void testMyTest(){

}

OR 

/**
 * My doc
 */
@Test
public void testMyTest(){

}
Freiheit
  • 8,408
  • 6
  • 59
  • 101

2 Answers2

7

I don't think it matters but second format is better. annotations are part of the code and play crucial role per their usage pattern. Better to keep all code related entries together.

Yogendra Singh
  • 33,927
  • 6
  • 63
  • 73
  • If annotations are part of the code, can the annotations be included in the javadoc? – Freiheit Nov 14 '12 at 19:25
  • @Freiheit: Yes e.g. `/** * This is my custom method. * @param param1 * @param param2 * @return outParam1 * @throws BusinessException */`. But in this case they are not part of the code. – Yogendra Singh Nov 14 '12 at 19:30
  • 1
    Not what I meant to ask, consider the example in my question. Is there JavaDoc indicating that I am using the @Test annotation? – Freiheit Nov 14 '12 at 20:47
  • 1
    @Freiheit: Since it is part of code, I don't think it is directly supported [**Java Doc Specifications**](http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html), but I think you can create a [**taglet**](http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/taglet/overview.html) as per your need. – Yogendra Singh Nov 14 '12 at 21:23
4

The usual style seems to be to have the annotation after the Javadoc comment.

The reason is that the annotations are part of the code, not of the documentation - why should the documentation sit inbetween.

This may not be obvious for @Override and @Test, and of course there are documentation related annotations, too. But technically, annotations are Java code of a particular syntax.

Has QUIT--Anony-Mousse
  • 76,138
  • 12
  • 138
  • 194