Javadoc coding standards by Stephen Colebourne.
From the post:
These are the standards I tend to use when writing Javadoc. Since personal tastes differ, I’ve tried to explain some of the rationale for some of my choices. Bear in mind that this is more about the formatting of Javadoc, than the content of Javadoc.
There is an Oracle guide which is longer and more detailed than this one. The two agree in most places, however these guidelines are more explicit about HTML tags, two spaces in @param and null-specification, and differ in line lengths and sentence layout.
Each of the guidelines below consists of a short description of the rule and an explanation, which may include an example:
Documentation of source code is vital to its maintenance. (cant)
But neither Stephen nor Oracle made much of the need to document the semantics of the source and/or data. If I am indexing/mapping across source files, <code> elements aren’t going to be enough to compare field names across documents.
I am assuming that semantic diversity is as present in source code as elsewhere. Would you assume otherwise?