Javadoc：Do 参数和 return 需要明确的类型描述

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/compiler 会为我处理这些？

Answer 1

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

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

来自那篇文章的 @param part：

The @param tag is followed by the name (not data type) of the parameter, followed by a description of the parameter. By convention, the first noun in the description is the data type of the parameter. (Articles like "a", "an", and "the" can precede the noun.) An exception is made for the primitive int, where the data type is usually omitted. Additional spaces can be inserted between the name and description so that the descriptions line up in a block. Dashes or other punctuation should not be inserted before the description, as the Javadoc tool inserts one dash.

Parameter names are lowercase by convention. The data type starts with a lowercase letter to indicate an object rather than a class.

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

@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：Do 参数和 return 需要明确的类型描述

Javadoc: Do parameter and return need an explicit type description

java

types

javadoc