CODEWITHSUNDEEP
javajavadoc
Beru
Beru

Reputation: 673

Javadoc - refere to a parameter from another point in the documentation something like @link

I have a class called ErrorHandler that takes care of all error message. Currently I am writing the JavaDoc for this class an have a problem. In my class I have several different pulic constants that describle all different error types.

A few examples:

/**
 * here I want to refere to parameter errorType
 */
public static void final String INVALID_COMMAND = "invalid_command";
public static void final String INVALID_NUMBER = "invalid_number";

These constants are used in my printErrorMessage method as a parameter to determin which error occured.

My method looks as follows:

/**
 * Prints an error message according to the type of error that is appended.
 *
 * @param errorType type of error that occurred
 * @see #INVALID_COMMAND
 * @see #INVALID_NUMBER
 */
public static void printErrorMessage(String errorType) {
    //does stuff
}

My queston now is: When I write the documentation of the constants, how do I refere to the parameter errorTypeto tell other deverlopers that my constants are used as errorType?

If my intention is not working as I'm expecting it to. Can someone tell me how it would be done.

Upvotes: 0

Views: 214

Answers (2)

Andreas
Andreas

Reputation: 159086

You can't link to the parameter, so you document the parameter name and link to the method.

/**
 * For use with the {@code errorType} parameter in
 * calls to {@link #printErrorMessage(String)}.
 */
public static final String INVALID_COMMAND = "invalid_command";

Result javadoc looks like this:

For use with the errorType parameter in calls to printErrorMessage(String).

As commented by Robert, you should consider using an enum instead of string constants.

/**
 * @see {@link MyClass#printErrorMessage(String) printErrorMessage(String typeName)}
 */
public enum ErrorType {
    INVALID_COMMAND("invalid_command"),
    INVALID_NUMBER("invalid_number");

    private final String typeName;

    private ErrorType(String typeName) {
        this.typeName = typeName;
    }
    public String getTypeName() {
        return this.typeName;
    }
}

/**
 * Prints an error message according to the type of error that is appended.
 *
 * @param errorType type of error that occurred
 * @see ErrorType#INVALID_COMMAND
 * @see ErrorType#INVALID_NUMBER
 */
public static void printErrorMessage(ErrorType errorType) {
    //does stuff
}

Upvotes: 1

Dmitrii
Dmitrii

Reputation: 1

You can use {@Value package.class#field} to specify possible constant values for you method.

For example:

/**
* Prints an error message according to the type of error that is appended.
*
* @param errorType type of error that occurred
* Possible values:
* {@value #INVALID_COMMAND},
* {@value #INVALID_NUMBER}
*/
public static void printErrorMessage(String errorType) {
    //does stuff
}

Or if you have a finite number of possible errorTypes you can create an enum class with mentioned String constants as a value. This way you specify allowed values explicitly and no one can pass some random string as an argument.

Update:

As mentioned @Andreas, in the code above link is between method -> constant. if you need the opposite relationship then you can use the following code:

/**
* Is used as a parameter for the {@link #printErrorMessage(String) errorType}
*/
public static final String INVALID_COMMAND = "invalid_command";
public static final String INVALID_NUMBER = "invalid_number";

Upvotes: 0

Related Questions