Java的注释说明

在Java里面主要有三种注释：行注释、段落注释、文档注释

　　1)行注释：行注释也成为单行注释，行注释使用 “//注释文字”的格式来对某一行的代码进行注释或者加以说明

public class LineComment

{

    //这是单行注释的范例

    public static void main(String args[])

    {

        //这只是一个单行注释的例子

        System.out.println("Single Line Comment");

    }

}

　　上边代码里面//后边的文字就是行注释的一个例子

　　2)段注释：段注释也成为多行注释，通常是当说明文字比较长的时候的注释方法

public class MultiCommont

{

    /*

     *这是段注释的一个简单的例子

     *这里是函数入口main方法

     */

    public static void main(String args[])

    {

        System.out.println("Multi Lines Comments");

    }

}

　　3)文档注释：文档注释是Java里面的一个比较厉害的功能，它可以用于注释类、属性、方法等说明，而且通过JDK工具javadoc直接生成相关文档，文档注释的基本格式为“/**...*/”，不仅仅如此，文档注释本身还存在语法

　　[1]文档和文档注释的格式化：

　　生成的文档是HTML格式的，而这些HTML格式的标识符并不是javadoc加的，而是我们在写注释的时候写上去的。因此在格式化文档的时候需要适当地加入HTML标签，例如：

/**

 *This is first line.<br/>

 *This is second line.<br/>

 *This is third line.<br/>

 **/

　　[2]文档注释的三部分：

　　根据在文档中显示的效果，文档注释可以分为三个部分，这里举个例子：

/**

 *testDoc方法的简单描述

 *<p>testDoc方法的详细说明</p>

 *@param testInput String 打印输入的字符串

 *@return 没有任何返回值

 **/

public void testDoc(String testInput)

{

    System.out.println(testInput);

}

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

　　详细说明：该部门对属性或者方法进行了详细说明，在格式上不需要特殊的要求，可以写成前边讲的HTML的格式，如同上边第二行的内容。【*：这里有个技巧就是简述和详细说明尽量不要重复，在简述中出现过的内容不需要在详细说明中进行第二次描述，可以理解为详细说明是简述的一种扩展。后边章节的概念说明代码大部分我都没有写注释，也请各位读者见谅！】

　　特殊说明：除开上边的两部分，最后一个部分就是特殊说明部分，特殊说明部分使用JavaDoc标记进行，这些都是JavaDoc工具能够解析的特殊标记，这一点下边章节将会讲到

　　[3]使用javadoc标记：

　　javadoc标记是java插入文档注释中的特殊标记，它们用于识别代码中的特殊引用。javadoc标记由“@”以及其后跟着的标记类型和专用注释引用组成。它的格式包含了三个部分：

　　@、标记类型、专用注释引用

　　有时候我们也可以直接理解为两个方面：@和标记类型、专用注释引用；Javadoc工具可以解析Java文档注释中嵌入的特殊标记，这些文档标记可以帮助自动从源代码生成完整的格式化API，标记用“@”符号开头，区分大小写，必须按照正确的大小写字母输入。标记必须从一行的开头开始，否则会被视为普通文本，而且按照规定应将相同名字的标记放一起，比如所有的@see标记应该放到一起，接下来看一看每一种标记的含义。

　　@author(1.0)：语法[@author name-text]

　　当使用-author选项的时候，用指定的name-text在生成文档的时候添加“Author”项，文档注释可以包含多个@author标记，可以对每个@author指定一个或者多个名字。

　　@deprecated(1.0)：语法[@deprecated deprecated-text]

　　添加注释，只是不应该再使用该API（尽管是可用的），Javadoc工具会将deprecated-text移动到描述前面，用斜体显示，并且在它前边添加粗体警告：“不鼓励使用”。deprecated-text的首句至少应该告诉用户什么时候开始不鼓励使用该API以及使用什么替代它。Javadoc仅将首句复制到概览部分和索引中，后面的语句还可解释为什么不鼓励使用，应该还包括一个指向替代API的{@link}标记【1.2版本用法】

对于Javadoc 1.2，使用{@link}标记，这将在需要的地方创建内嵌链接，如：

/**

 *@deprecated 在JDK X.X中，被{@link #methodName(paramList)}取代

 **/

【*：在上边的标记里面X.X指代JDK的版本，后边的链接链接的是方法的签名，methodName为方法名，paramList为参数列表】

对于Javadoc 1.1，标准格式是为每个@deprecated标记创建@see标记（它不可内嵌）

　　@exception(1.0)：语法[@exception class-name description]

　　@throws(1.2)：语法[@throws class-name description]

　　以上两个标记是同义词，用class-name和description文本给生成的文档添加“抛出”子标题，其中class-name是该方法可抛出的异常名。

　　{@link}(1.2)：语法[{@link name label}]

　　出入指向指定name的内嵌链接，该标记中name和label的语法与@see标记完全相同，如下所述，但是产生的内嵌链接而不是在“参见”部分防止链接。该标记用花括号开始并用花括号结束，以使它区别于其他内嵌文本，如果需要在标签内使用“}”，直接使用HTML的实体表示法：&#125;

　　@param(1.0)：语法[@param parameter-name description]

　　给“参见”部分添加参数，描述可以继续到下一行进行操作，主要是提供了一些参数的格式以及描述

　　@return(1.0)：语法[@return description]

　　用description本文添加“返回”部分，该文本应描述值的返回类型和容许范围

　　@see(1.0)：语法[@see reference]

　　该标记是一个相对复杂的标记，添加“参见”标题，其中有指向reference的链接或者文本项，文档注释可包含任意数目的@see标记，它们都分组在相同的标题下，@see有三种格式：

@see “string” 注：该形式在JDK 1.2中没有用，它不打印引用文本

为string添加文本项，不产生链接，string是通过该URL不可用的书籍或者其他信息引用，Javadoc通过查找第一个字符为双引号（"）的情形来区分它前边的情况，比如：

@see "这是Java教材，主要是提供给初学者"

上边的注释将会生成：

参见：

　　“这是Java教材，主要是提供给初学者”

@see <a href="page.html#section">Java某章节</a>

添加URL#value定义的链接，其中URL#value是相对URL或者绝对URL，JavaDoc工具通过查找第一个字符小写符号（<）区分它与其他情况，比如：

@see <a href="page.html#section">测试规范</a>

上边的注释将会生成：

参见：

　　测试规范

@see package.class#member label【比较常用的一种格式】

添加带可见文本label的链接，它指向Java语言中指定名字的文档。其中label是可选的，如果省略，则名字作为可见文本出现，而且嵌在<code>HTML标记中，当想要缩写可见文本或不同于名字的可见文本的时候，可以使用label。

——package.class#member是Java语言中的任何有效名字——包名、类名、接口名、构造函数名、方法名或域名——除了用hash字符(#)取代成员名前面的点之外，如果该名字位于带文档的类中，则Javadoc将自动创建到它的链接，要创建到外部的引用链接，可使用-link选项，使用另外两种@see形式中的任何一种引用不属于引用类的名字的文档。

——label是可选文本，它是链接的可见标签，label可包含空白，如果省略label，则将显示package.class.member，并相对于当前类和包适当缩短

——空格是package.class#member和label之间的分界符，括号内的空格不表示标签的开始，因此在方法各参数之间可使用空格

@see package.class#member的典型形式

引用当前类的成员

@see #field

@see #method(Type,Type,...)

@see #method(Type argname,Type argname,...)

引用当前包或导入包中的其他类

@see Class#field

@see Class#method(Type,Type,...)

@see Class#method(Type argname,Type argname,...)

@see Class

引用其他包（全限定）

@see package.Class#field

@see package.Class#method(Type,Type,...)

@see package.Class#method(Type argname,Type argname,...)

@see package.Class

@see package简单说明一下：

——第一套形式（没有类和包）将导致 Javadoc 仅搜索当前类层次。它将查找当前类或接口、其父类或超接口、或其包含类或接口的成员。它不会搜索当前包的其余部分或其他包（搜索步骤 4-5）。

——如果任何方法或构造函数输入为不带括号的名字，例如 getValue，且如果没有具有相同名字的域，则 Javadoc 将正确创建到它的链接，但是将显示警告信息，提示添加括号和参数。如果该方法被重载，则 Javadoc 将链接到它搜索到的第一个未指定方法。

——对于所有形式，内部类必须指定为 outer.inner，而不是简单的 inner。

——如上所述，hash 字符（#）而不是点（.）用于分隔类和成员。这使 Javadoc 可正确解析，因为点还用于分隔类、内部类、包和子包。当 hash 字符（#）是第一个字符时，它是绝对不可少的。但是，在其他情况下，Javadoc 通常不严格，并允许在不产生歧义时使用点号，但是它将显示警告。

　　@see标记的搜索次序——JavaDoc将处理出现在源文件（.java）、包文件（package.html）或概述文件（overview.html）中的@see标记，在后两种文件中，必须完全限定使用@see提供的名字，在源文件中，可指定全限定或部分限定的名字，@see的搜索顺序为：

当前类或接口

任何包含类和接口，先搜索最近的

任何父类和超接口，先搜索最近的

当前包

任何导入包、类和接口，按导入语句的次序搜索

　　@since(1.1)：语法[@since since-text]

　　用since-text指定的内容给生成文档添加“Since”标题，该文本没有特殊内部结构，该标记表示该改变或功能自since-text所指定的软件件版本后就存在了，例如：@since JDK 1.4

　　@serial(1.2)：语法[@serial field-description]

　　用于缺省的可序列化域的文档注释中，可选的field-description增强了文档注释对域的描述能力，该组合描述必须解释该域的意义并列出可接受值，如果有需要描述可以多行，应该对自Serializable类的最初版本之后添加的每个可序列化的域添加@since标记。

　　@serialField(1.2)：语法[@serialField field-name field-type field-description]

　　简历Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档，应该对每个ObjectStreamField使用一个@serialField标记

　　@serialData(1.2)：语法[@serialData data-description]

　　data-description建立数据（尤其是writeObject方法所写入的可选数据和Externalizable.writeExternal方法写入的全部数据）序列和类型的文档，@serialData标记可用于writeObject、readObject、writeExternal和readExternal方法的文档注释中

　　@version(1.0)：语法[@version version-text]

　　当使用-version选项时用version-text指定的内容给生成文档添加“版本”子标题，该文本没有特殊内部结构，文档注释最多只能包含一个@version标记。

　　{@code}(1.5)：语法[{@code text}]

　　该标签等同于<code>{@literal}</code>，里面可以直接过滤掉HTML的标签，可以不用&lt;和&gt;来显示（<和>），在这个代码块里面的text部分，可以直接书写代码，即使使用了<b>Hello</b>，在HTML里面也不会识别成为加粗的Hello，而还是原来的代码段<b>Hello</b>的格式输出

　　{@docRoot}(1.3)：语法[{@docRoot}]

　　代表相对路径生成的文件的（目标）的根从任何产生的网页目录，当您要包括如版权页或公司徽标文件的时候它是有用的，你要引用所生成的网页，链接从每个页面底部的版权页面是常见的。（@docRoot将标记可用于在命令行，并在两个文档注释：这个标记是有效的，在所有文档注释：概述、包装类、接口、构造、方法和领域，包括任何标记文本的一部分（如@return ，@param和@deprecated的使用）。

　　比如：

/** 

 * See the <a href="{@docRoot}/copyright.html">Copyright</a>. 

 **/

　　{@inheritDoc}(1.4)：语法[{@inheritDoc}]

　　继承（拷贝）文档从最近的“继承类或可执行的接口”到当前在这个标签的位置的文档注释内容，这使您可以编写更多与继承相关的一般性文档

　　下边的情况比较适合：

在一个方法的主要描述块，在这种情况下，主要描述是整个继承树结构里面的类和接口的一个拷贝。

在文本参数返回的@return @param和@throws等方法标记，在这种情况下，文本标记是整个层次结构里面标签的拷贝。

　　{@linkplain}(1.4)：语法[{@linkplain package.class#member label}]

　　和{@link}类似，除非链接的label是用普通文本的格式显示的，当文本是普通文本的时候该标签就能够起作用，例如：

Refer to {@linkplain add() the overridden method}

　　这个会显示成：

Refer to the overridden method

　　{@value}(1.4)：语法[{@value package.class#field}]

　　主要用来显示静态字段的值：

/**

 * The value of this constant is {@value}

 **/

public static final String SCRIPT_START = "script";

　　[4]JavaDoc标记的举例：

　　——[$]一个使用JavaDoc标记的例子——

/**

 * @author Lang Yu

 * @version 1.2

 */

public class JavaDocBasic {

    /**

     * @see "Main Function JavaDoc"

     * @since JDK 1.4

     * @param args The params of console

     **/

    public static void main(String args[]){

        System.out.println("Hello World!");

    }

}

　　例如有这样一小段代码，在我机器上我放在了D:\Source\work下，然后进入该目录下，使用下边的命令：

D:\Source\work>javadoc -d doc JavaDocBasic.java

　　通过这样的命令使用，在执行该命令了过后电脑上有下边这样的输出，而且去目录下边可以看到一个doc文件夹，用浏览器打开里面的index.html就可以看到生成的文档的内容：

Loading source file JavaDocBasic.java...

Constructing Javadoc information...

Standard Doclet version 1.6.0_16

Building tree for all the packages and classes...

Generating doc\JavaDocBasic.html...

Generating doc\package-frame.html...

Generating doc\package-summary.html...

Generating doc\package-tree.html...

Generating doc\constant-values.html...

Building index for all the packages and classes...

Generating doc\overview-tree.html...

Generating doc\index-all.html...

Generating doc\deprecated-list.html...

Building index for all classes...

Generating doc\allclasses-frame.html...

Generating doc\allclasses-noframe.html...

Generating doc\index.html...

Generating doc\help-doc.html...

Generating doc\stylesheet.css...

　　——[$]一个使用{@link}的例子——

/**

 * @author Lang Yu

 * @see java.lang.String

 */

public class JavaDocLink {

    private int a;

    private int b;

    /**

     * {@link #getAdd() getAdd()} Method

     * @return the result of (a + b)

     **/

    public int getAdd(){

        return a + b;

    }

}

原文地址： http://blog.csdn.net/silentbalanceyh/article/details/4608272