Search code examples
javadocumentationjavadoc

Is there an "example use" or "example" Javadoc tag?

Is there a tag (or a conventional custom tag) for the Javadoc tool that can be used to explain an illustrative use case of a given method?

Example:

/**
 * Returns the sum of all the elements in an integer array.
 * 
 * @param numbers Array of integers to be summed.
 * @example {@code sum(1, 2, 3); -> 6}
 */
public int sum(int... numbers) {

    int tally = 0;

    for (int i = 0; i < numbers.length; i++) {
        tally += numbers[i]
    }
    
    return tally
}

In the simple example above, the @example tag provides a quick demonstration of the method.

Solution

  • No, there is no such tag, although you should check out the latest extensions to the JavaDoc tool that allows to add sample code to the JavaDoc documentation (keyword: @snippet).

    If this is not what you want, or you want it differently, you can implement your own JavaDoc tag quite easily.

    You can find documentation related to @snippet here:

    Have fun!