Javadoc：做参数并返回需要明确的类型描述

Question

使用Javadocing时，我不知道您是否应该明确说明参数是类型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 / compiler帮我解决这个问题？

Answer 1

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

Oracle Java网站上的本文可能会有用：如何为Javadoc工具编写文档注释

从该文章的@param部分来看：

@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

从详细示例中也可以清楚地看出。