Javadoc

Question

我有一个名为 ErrorHandler 的 class 负责处理所有错误消息。目前，我正在为此 class 编写 JavaDoc，但遇到了问题。在我的 class 中，我有几个不同的公共常量来描述所有不同的错误类型。

举几个例子：

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

如果我的意图没有达到预期效果。谁能告诉我怎么做。

Answer 1

您可以使用 {@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
}

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

更新：

如@Andreas 所述，在上面的代码中 link 在方法 -> 常量之间。如果你需要相反的关系那么你可以使用下面的代码：

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

Answer 2

您不能 link 到参数，因此您记录了 参数名称 和 link 方法.

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

结果 javadoc 如下所示：

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

作为，您应该考虑使用 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
}

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

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

java