Add Javadoc documentation

[CSchoel]

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]

Starting with method documentation