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 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
    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, 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> {}

A is a file used to document a package.

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