JavaDoc for Method with Multiple Signatures

Question

Suppose I have a method with multiple signatures (just a silly example). The method with all parameters is the actuall workhorse and all other methods are convenience shortcuts.

I have documented the workhorse method using JavaDoc. Since all other methods work the same I do not want to duplicate the documentation.

Is there a way in JavaDoc to link to the full documentation - or some other way to not have to re-write the documentation over and over again?

    /**
     * Function to format a string
     * 
     * @param s string to be formatted
     * @param bold string should be bold?
     * @param cursive string should be cursive?
     *                
     * @return a formatted string 
     */
    public static String formatMe(String s, Boolean bold, Boolean cursive){
        String res = s;

        // handle bold option
        if (bold) {
            res = "BOLD" + res + "BOLD";
        }

        // handle cursive option
        if (cursive) {
            res = "KURSIVE" + res + "KURSIVE";
        }

        // return
        return res;
    }

    public static String formatMe(){
        return formatMe("", false, false);
    }
    
    public static String formatMe(String s){
        return formatMe(s, false, false);
    }```

Answer 1

Yes … no …

The OOTB JavaDoc does not provide a functionality to have the same documentation for a group of methods (or other elements). But you can refer to an already existing documentation, like this:

/**
 * Function to format a string.
 * 
 * @param s The string to be formatted.
 * @param bold {@code true} if the string should be bold, {@code false}
 *    otherwise.
 * @param cursive {@code true} if the string should be cursive, {@code false}
 *    otherwise.
 * @return A formatted string.
 */
public static String formatMe( final String s, final boolean bold, final boolean cursive )
{
    var retValue = s;

    // handle bold option
    if( bold ) retValue = "BOLD" + retValue + "BOLD";

    // handle cursive option
    if( cursive ) retValue = "KURSIVE" + retValue + "KURSIVE";

    // Done!
    return retValue;
}

/**
 * Function to format a string.
 * 
 * Calls
 * {@link #formatMe(String,boolean,boolean)}
 * with the arguments {@code "",false,false}.
 *
 * @return A formatted string. 
 *
 */
public static String formatMe()
{
    return formatMe( "", false, false );
}

/**
 * Function to format a string.
 * 
 * Calls
 * {@link #formatMe(String,boolean,boolean)}
 * with the arguments {@code s,false,false}.
 *
 * @param s The string to be formatted.
 * @return A formatted string.
 */
public static String formatMe( String s )
{
    return formatMe( s, false, false );
}

Alternatively, you can implement your own JavaDoc tag that works along the lines of {@inheritDoc}:

/**
 * Function to format a string.
 * 
 * @param s The string to be formatted.
 * @param bold {@code true} if the string should be bold, {@code false}
 *    otherwise.
 * @param cursive {@code true} if the string should be cursive, {@code false}
 *    otherwise.
 * @return A formatted string. 
 */
public static String formatMe( final String s, final boolean bold, final boolean cursive )
{
    var retValue = s;

    // handle bold option
    if( bold ) retValue = "BOLD" + retValue + "BOLD";

    // handle cursive option
    if( cursive ) retValue = "KURSIVE" + retValue + "KURSIVE";

    // Done!
    return retValue;
}

/**
 * {@copyDoc #formatMe(String,boolean,boolean)}
 */
public static String formatMe()
{
    return formatMe( "", false, false );
}

/**
 * {@copyDoc #formatMe(String,boolean,boolean)}
 */
public static String formatMe( String s )
{
    return formatMe( s, false, false );
}

Your new tag can copy the @return tag and those @param tags that match the current signature plus the general description.

But me personally, I just use copy, paste and edit instead.