What's the best way to handle/format Javadoc and annotations in code? [duplicate]

Question

I've looked across this forum, and I've googled this one, and I'm not sure what is the best way to handle Javadoc and annotations that appear together in the same class.

From what I can see from Sun/Oracle's documentation, they seem to suggest (though I cannot really find an explicit statement) that Javadoc should be listed atop annotations.

See their example How and When to Deprecate API's.

That works great for something simple like @Deprecated or @Override. But what about if you use JPA and/or Hibernate? Your classes and methods are bound to be annotated quite a bit more heavily (sometimes two or more annotations per class or method).

I'm guessing Javadoc still on top of annotations?

Also I wonder how should annotations best be used? I've seen some examples where the annotations "stack" on top of the class, member, method. And I've seen others where they list the annotations on the same line (usually a method here).

Which is best? Which is more readable?

And do you "document" that fact that you annotated something within your Javadoc or not?

I'm looking for either a good set of documentation about this and/or your own experience about what is most readable/maintainable.

Answer 1

Javadoc is only place where you document class, method, etc. Annotations can change functionality of given code (like annotations from Hibernate or Spring). So, for me, it is obvious that annotations should be closer to code (so, between javadoc and method/function).

But how to write annotations, where there is lot of them? It depends, I prefer to leave them in separated lines, with few exceptions if there are short and connected in some way.

Explicit documenting in Javadoc that you are using annotations is not a good idea i think. Annotations can have @Documented annotations themselves, which states they should appear in generated javadocs. Beside this, it is implementation detail - javadoc should tell what method/object is made for, not how you are doing that (mostly, at least).