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

Question

当Javadoc'ing时，我不知道您是否应该明确说明参数的类型是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代码并从那里获取类型。

本文甲骨文的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。