Javadoc

The Javadoc is java documentation engine ✍️. Developers will write Javadoc comments inside their code, and using the javadoc command, a website will be generated 🌍.

Aside from versions before 11, you can change the number in the URL to access the Javadoc for another version of Java at:

❌ Don't write meaningless documentation.

  • the type of an argument for primitive types (for objects, it's ~OK)
  • a trivial getter/setter/constructor

✅ Write useful stuff such as:

  • ranges, intervals, preconditions (not null...)
  • exceptions
  • post-conditions (null->null, not null->not null...)
  • examples of calling a class/method/...
  • ...

Writing Javadoc

Javadoc comments are comments starting with /**.

/**
 * Class description
 *
 * @author author
 * @version 0.0.0.1 09 November 2019
 * @see AnotherClassYouMustCheck
 * @see AnotherClassYouMustCheck#aMethodName
 */
public class AClass {

    /**
     * Method description
     *
     * @param a description
     * @param b description
     *
     * @return description
     *
     * @throws UnsupportedOperationException description
     * @see UnsupportedOperationException
     * @see #aDeprecatedMethod()
     *
     * @since 0.0.0.1
     */
    public ATypeHere methodName(int a, float b) {
        // code
    }

    /** @deprecated no reason */
    public void aDeprecatedMethod(){ /* ... */ }

}

Explanations ✍️

Most elements are not present in every Javadoc comment, albeit you may see some warnings if according to the context, one is missing.

  • @author author: can have multiple authors tags or a list of authors

  • @version version: for instance, 1.0.0.0 xxxx-xx-xx

  • @since version: since which version this was added

  • @see xxx: a class or a method the reader should check too

    • @see class
    • @see class#method
       

  • @deprecated why: why we should not use it

  • {@link xxxx}: inside a param, a return, or some text, you can use this to create a link to a class/method.

  • @param name desc: describe a param

  • @return desc: describe what the method returns

  • @throws exception_class desc: if an exception is thrown

To comment on a generic class/method parameter, use @param too:

/**
 * ...
 * @param <T> description
 */
public class GenericClass<T> {}

package-info.java

A package-info.java is a file used to document a package.

/**
* Some Javadoc here
*
* @author xxx
* @version yyy
*/
package com.lgs.memorize;