5.2 文档注释(Documentation Comments)
注意:此处描述的注释格式之范例,参见"Java源文件范例"
若想了解更多,参见"How to Write Doc Comments for Javadoc",其中包含了有关文档注释标记的信息(@return, @param, @see):
http://java.sun.com/javadoc/writingdoccomments/index.html
若想了解更多有关文档注释和javadoc的详细资料,参见javadoc的主页:
http://java.sun.com/javadoc/index.html
文档注释描述Java的类、接口、构造器,方法,以及字段(field)。每个文档注释都会被置于注释定界符/**...*/之中,一个注释对应一个类、接口或成员。该注释应位于声明之前:
/**
* The Example class provides ...
*/
public class Example { ...
注意顶层(top-level)的类和接口是不缩进的,而其成员是缩进的。描述类和接口的文档注释的第一行(/**)不需缩进;随后的文档注释每行都缩进1格(使星号纵向对齐)。成员,包括构造函数在内,其文档注释的第一行缩进4格,随后每行都缩进5格。
若你想给出有关类、接口、变量或方法的信息,而这些信息又不适合写在文档中,则可使用实现块注释(见5.1.1)或紧跟在声明后面的单行注释(见5.1.2)。例如,有关一个类实现的细节,应放入紧跟在类声明后面的实现块注释中,而不是放在文档注释中。
文档注释不能放在一个方法或构造器的定义块中,因为Java会将位于文档注释之后的第一个声明与其相关联。
6 声明(Declarations)
6.1 每行声明变量的数量(Number Per Line)
推荐一行一个声明,因为这样以利于写注释。亦即,
int level; // indentation level
文章来源于领测软件测试网 https://www.ltesting.net/