java注释

 1、单行(single-line)--短注释：//……   
单独行注释：在代码中单起一行注释， 注释前最好有一行空行，并与其后的代码具有一样的缩进层级。如果单行无法完成，则应采用块注释。
注释格式：/* 注释内容 */
行头注释：在代码行的开头进行注释。主要为了使该行代码失去意义。
注释格式：// 注释内容
行尾注释：尾端(trailing)--极短的注释，在代码行的行尾进行注释。一般与代码行后空8（至少4）个格，所有注释必须对齐。
注释格式：代码 + 8（至少4）个空格 + // 注释内容

2、块(block)--块注释：/*……*/
注释若干行，通常用于提供文件、方法、数据结构等的意义与用途的说明，或者算法的描述。一般位于一个文件或者一个方法的前面，起到引导的作用，也可以根据需要放在合适的位置。这种域注释不会出现在HTML报告中。注释格式通常写成：
/*
  * 注释内容
  */ 

 

 3、文档注释：/**……*/
注释若干行，并写入javadoc文档。每个文档注释都会被置于注释定界符
/**......*/之中，注释文档将用来生成HTML格式的代码报告，所以注释文
档必须书写在类、域、构造函数、方法，以及字段(field)定义之前。注释文档由两部分组成——描述、块标记。

     <1>文档和文档注释的格式化

               因为生成的文档是HTML 格式，所以格式化文档就是在注释间添加相应的HTML 标识

               注意：文档注释只说明紧接其后的类、属性或者方法。

      <2>注释的三部分

               eg：

                    /**

           * show 方法的简述.
           * <p>show 方法的详细说明第一行<br>
           * show 方法的详细说明第二行
           * @param b true 表示显示，false 表示隐藏
           * @return 没有返回值
           */
          public void show(boolean b) {
              frame.show(b);
          }

                第一部分是简述。文档中，对于属性和方法都是先有一个列表，然后才在后面一个一个的详细的说明。列表中属性名或者方法名后面那段说明就是简述。

                第二部分是详细说明部分。该部分对属性或者方法进行详细的说明，在格式上没有什么特殊的要求，可以包含若干个点号。

                第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。

 

4、javadoc注释标签语法

 javadoc 标记是插入文档注释中的特殊标记，它们用于标识代码中的特殊引用。javadoc 标记由“@”及其后所跟的标记类型和专用注释引用组成。记住了，三个部分——@、标记类型、专用注释引用。

@author    对类的说明 标明开发该类模块的作者
@version   对类的说明 标明该类模块的版本
@see      对类、属性、方法的说明 参考转向，也就是相关主题
@param    对方法的说明 对方法中某参数的说明
@return    对方法的说明 对方法返回值的说明
@exception  对方法的说明 对方法可能抛出的异常进行说明 

 

5、javadoc命令

 

 运行 javadoc -help 可以看到 javadoc 的用法

eg：

javadoc -d 文档存放目录 -author -version 源文件名.java

　　这条命令编译一个名为 “源文件名.java”的 java 源文件，并将生成的文档存放在“文档存放目录”指定的目录下，生成的文档中 index.html 就是文档的首页。-author 和 -version 两个选项可以省略。

 

 

更多有关文档注释和javadoc的详细资料，参见javadoc的主页： http://java.sun.com/javadoc/index.html