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

【问题标题】：Javadoc - refere to a parameter from another point in the documentation something like @linkJavadoc - 从文档中的另一个点引用参数，例如 @link
【发布时间】：2021-02-17 10:56:47
【问题描述】：

我有一个名为 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？

如果我的意图没有像我期望的那样工作。谁能告诉我怎么做。

【问题讨论】：

应该是@param errorType
@Tushortz @param 将用于为我的方法记录 errorType。但是，我想记录我的常量。
您可以为您的错误类型创建一个enum，而不是依赖文档。

标签： java javadoc

【解决方案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
}

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

更新：

正如@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";

【讨论】：

OP 要求链接另一种方式，即字段链接到方法的参数。

【解决方案2】：

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

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

【讨论】：