Tuesday, November 13, 2018

Tips for writing your Javadoc

In Javadoc you have nine tags which are the following:

  • @author
  • @version
  • @param
  • @return
  • @exception/@throws
  • @see
  • @since
  • @serial/@serialField/@serialData
  • @deprecated

Use @code for code snippets

Often you can find some code inside a Javadoc to illustrate how to use a method, class or to provide some other example. In order to display the code correctly and preventing some markup to be interpreted such as <String> and so on, you can use the @code.
{@code 
List<I88ca> i88cas = new ArrayList<>();
  for(int index = 0; index < 10; index++) {
    i88cas.add(new I88ca(I88ca #” + index)); 
  }
}

Use @link and @linkplain for pointing to some code

In my Javadoc I like to refer to classes and methods if there is a dependency or if it is just useful for the documentation. In order to make it easier to navigate through methods and classes, you can use @link. It works like this:
  • {@link I88caDepartment} to point to a class
  • {@link I88caDepartment testers manager} to point to a class with a given label
  • {@link #dev(Developer, boolean)} to point to a method inside the same class
  • {@link #eat(Developer, boolean) qa} to point to a method inside the same class with a given label
  • {@link I88caDepartment#dev(Developer, boolean)} to point to a method inside another class
  • {@link I88caDepartment#dev(Developer, boolean) burgers manager eat} to point to a method inside another class with a given label.
The difference between @link and @linkplain is that the latter one doesn’t produce a monospaced code font.

Use @value to insert the value of a field in the documentation


/**
 * The default value for this field is {@value}.
*/
public static final String I88_CA_NAME = "I88CA";


you can also refer to another constant, for example:
/**
 * The default value for this field is {@value} The value 
 * of {@link #PI} is {@value #PI}.
 */
public static final String I88_CA_NAME = "I88CA";
 
public static final double PI = 3.14159265358979;

Indicate when the features have been available with @since

It is often useful to indicate when a class or a method became available in your code. For this you use the @since tag followed by the version/year since the feature or class has been implemented:
/**
 * This awesome class is for doing awesome things
 * @since i88ca-1.88
 * @version 2.88
*/
public class I88caDeveloper {
 
  /**
   * Allows to dev i88ca
   * @since i88ca-1.88

   */
  public void dev(I88ca i88ca, boolean fast) {
    // TODO
  }
}

{@inheritDoc} copies the description from the overridden method for your Overriding Method.