11.10 JavaDocs

JavaDoc comments are a special type of comment used to document parts of your code, such as a method, variable (aka field), or class (see Ch. 12). A JavaDoc comment for a method can describe its purpose, its parameters, what it returns (assuming the method is not void), and more. The descriptions for the parameters and return value are marked with their respective tags (@param and @return).

/**
     * Returns the average of two doubles
     * @param a  first double
     * @param b  second double
     * @return the average of two doubles
     */
    public static double average(double a, double b) {
        return (a + b) / 2;
    }