Javadoc-从文档的另一点引用参数，例如@link

问题描述

我有一个名为ErrorHandler的类，该类负责处理所有错误消息。目前，我正在为此类编写JavaDoc，但有问题。在我的课堂上，我有几个不同的Pulic常量，可以描述所有不同的错误类型。

一些例子：

/**
 * 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";

这些常量在我的printErrorMessage方法中用作确定发生错误的参数。

我的方法如下：

/**
 * 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
}

现在的问题是：在编写常量文档时，如何引用参数errorType来告诉其他开发者我的常量用作errorType？

如果我的意图没有按预期的那样起作用。有人可以告诉我该怎么做。

解决方法

您无法链接到参数，因此您要记录参数名称并链接到方法。

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

结果javadoc看起来像这样：

用于在printErrorMessage(String)的调用中与errorType参数一起使用。

作为commented by Robert，您应该考虑使用enum代替字符串常量。

/**
 * @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
}

您可以使用{@Value package.class#field}为您的方法指定可能的常数值。

例如：

/**
* 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
}

或者，如果您有有限数量的可能的errorType，则可以创建一个枚举类，其中包含提到的String常量作为值。这样，您可以明确地指定允许的值，并且没有人可以传递一些随机字符串作为参数。

更新：

如@Andreas所述，在上面的代码中，链接位于方法->常量之间。如果您需要相反的关系，则可以使用以下代码：

/**
* 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";

java java javadoc javadoc