Question

当Javadoc时，我不知道你是否应该明确说明参数是String还是int。例如

/**
 * This method does something
 * @param foo an object of type Foo
 * @param abc the number of doors, of type int
 * @return the number of windows, of type int
 */
public int doSomething(Foo foo, int abc) {
    // Do something
}

我使用eclipse，所以当我查看Javadoc的用户端时，所有内容都有类型描述，eclipse告诉我何时使用了错误的类型引用。

那么，我应该包含上面的类型描述，还是Javadoc /编译器会为我处理这个？

Answer 1

不，没有必要，JavaDoc工具解析Java代码并从那里获取类型。

Oracle Java站点上的这篇文章可能很有用：How to Write Doc Comments for the Javadoc Tool

来自该文章的@param part：

@param标记后跟参数的名称（不是数据类型），后跟参数说明。按照惯例，描述中的第一个名词是参数的数据类型。（诸如“a”，“an”和“the”之类的文章可以在名词之前。）对于原语int进行例外处理，其中通常省略数据类型。可以在名称和描述之间插入额外的空格，以便描述在块中排列。在描述之前不应插入破折号或其他标点符号，因为Javadoc工具会插入一个破折号。

参数名称按惯例为小写。数据类型以小写字母开头，表示对象而不是类。

... 听起来就像它不同意我上面的说法。这只是糟糕的写作，正如它给出的例子所表明的那样：

@param ch the character to be tested

@param observer the image observer to be notified

@param x the x-coordinate, measured in pixels

the detailed examples也明确了这一点。

Javadoc：参数和返回需要显式类型描述

1 个答案: