Each public method of publicly available classes/interfaces must be documented with a Javadoc comment, which should look as follows:
/**
* <p>One sentence that clearly explains what the method does.</p>
*
* <p>Any additional information that is relevant about the behavior of the method but that
* does not reveal implementation-specific details.</p>
*
* <p>If needed, you can use mutliple paragraphs with <b>HTML</b> formatting or
* Javadoc-Tags like {@literal @link}.</p>
*
* @author Name of the method author responsible for writing and/or maintaining this code.
* @param nameOfFirstParameter description of the first parameter, including any special
* requirements about the parameter content or structure
* @param nameOfSecondParameter same for second parameter
* @return description of return value and its structure and content (yo do not have to
* describe the <i>type</i>, because that is also apparent from the method signature.
* @throws NameOfException explain in which cases the exception is thrown
* @see <a href="https://docs.oracle.com/javase/1.5.0/docs/tooldocs/solaris/javadoc.html">Javadoc documentation</a>
* @see name.of.relevant.Class#orMethod
*/
All methods that are implemented from an interface or inherited from a parent class should have the @Override annotation. For these methods it is OK to leave out the Javadoc comment if and only if...
The parent method has a Javadoc comment.
The implementation behaves exactly as described in the parent Javadoc. If this is not true and there are changes to the specification of the parent method, you should use {@inheritDoc} to copy the documentation of the parent and then add your own comments at the bottom.
Additionally, all classes or interfaces that are publicly accessible should also receive a similar comment of the following form:
/**
* <p>One sentence that clearly explains what kind of thing the class represents.</p>
*
* <p>Any additional information that is relevant about the behavior of the class.
* This can include small code examples that explain how to use this class, or - in
* the case of an interface documentation or abstract class a guide how to implement
* this interface / extend this class.</p>
*
* @author Name of the class/interface author responsible for writing and/or maintaining this code.
* @see <a href="https://docs.oracle.com/javase/1.5.0/docs/tooldocs/solaris/javadoc.html">Javadoc documentation</a>
* @see name.of.relevant.Class#orMethod
Note that you will not see javadoc errors until you actually use the gradle task javadoc. Please do that to make sure that your documentation is correct.
Summing up:
[ ] Add a Javadoc comment to each public method of publicly available classes/interfaces.
[ ] Add a Javadoc comment to all publicly accessible classes and interfaces.
[ ] Use appropriate Javadoc tags wherever possible.
[ ] Make sure that the documentation does not contain implementation-specific details that are not part of the specification what the class/method should do.
[ ] Check the correctness of your Javadoc tasks with ./gradlew javadoc (or the javadoc Gradle task in IntelliJ).
IlmarB
commented
3 years ago
Each public method of publicly available classes/interfaces must be documented with a Javadoc comment, which should look as follows:
All methods that are implemented from an interface or inherited from a parent class should have the
@Overrideannotation. For these methods it is OK to leave out the Javadoc comment if and only if...{@inheritDoc}to copy the documentation of the parent and then add your own comments at the bottom.Additionally, all classes or interfaces that are publicly accessible should also receive a similar comment of the following form:
Note that you will not see javadoc errors until you actually use the gradle task
javadoc. Please do that to make sure that your documentation is correct.Summing up:
./gradlew javadoc(or thejavadocGradle task in IntelliJ).