如何解决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";
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。