在Java里面主要有三种注释：行注释、段落注释、文档注释
这里主要说第三种：文档注释
文档注释是Java里面的一个比较厉害的功能，它可以用于注释类、属性、方法等说明，而且通过JDK工具javadoc直接生成相关文档，
文档注释的基本格式为：
/**
*.....注释内容1....
*.....注释内容2....
*/不仅仅如此，文档注释本身还存在语法
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);
}2.1-简述(第一部分)：
文档中，对于属性和方法都是现有一个列表，然后才在后面一个一个的详细说明，列表中属性名或者方法名后面那段说明都是简述。
2.2-详细说明(第二部分)：
该部门对属性或者方法进行了详细说明，在格式上不需要特殊的要求，可以写成前边讲的HTML的格式，如同上边第二行的内容。
【*：这里有个技巧就是简述和详细说明尽量不要重复，在简述中出现过的内容不需要在详细说明中进行第二次描述，可以理解为详细说明是简述的一种扩展。后边章节的概念说明代码大部分我都没有写注释，也请各位读者见谅！】
2.3-特殊说明(第三部分)：
除开上边的两部分，最后一个部分就是特殊说明部分，特殊说明部分使用JavaDoc标记进行，这些都是JavaDoc工具能够解析的特殊标记，这一点下边章节将会讲到
3、使用javadoc标记：
javadoc标记是java插入文档注释中的特殊标记，它们用于识别代码中的特殊引用。
javadoc标记由“@”以及其后跟着的标记类型和专用注释引用组成。
它的格式也包含了三个部分：
3.1-@、标记类型、专用注释引用
有时候我们也可以直接理解为两个方面：@和标记类型、专用注释引用；
Javadoc工具可以解析Java文档注释中嵌入的特殊标记，这些文档标记可以帮助自动从源代码生成完整的格式化API，
标记用“@”符号开头，区分大小写，必须按照正确的大小写字母输入。
标记必须从一行的开头开始，否则会被视为普通文本，而且按照规定应将相同名字的标记放一起，
比如所有的@see标记应该放到一起，接下来看一看每一种标记的含义。
3.2-@author(1.0)：语法[@author name-text]
当使用-author选项的时候，用指定的name-text在生成文档的时候添加“Author”项，文档注释可以包含多个@author标记，可以对每个@author指定一个或者多个名字。
3.3-@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标记（它不可内嵌）
3.4-@exception(1.0)：语法[@exception class-name description]
3.5-@throws(1.2)：语法[@throws class-name description]
以上两个标记是同义词，用class-name和description文本给生成的文档添加“抛出”子标题，其中class-name是该方法可抛出的异常名。
3.6-{@link}(1.2)：语法[{@link name label}]
出入指向指定name的内嵌链接，该标记中name和label的语法与@see标记完全相同，如下所述，但是产生的内嵌链接而不是在“参见”部分防止链接。该标记用花括号开始并用花括号结束，以使它区别于其他内嵌文本，如果需要在标签内使用“}”，直接使用HTML的实体表示法：}
3.7-@param(1.0)：语法[@param parameter-name description]
给“参见”部分添加参数，描述可以继续到下一行进行操作，主要是提供了一些参数的格式以及描述
3.8-@return(1.0)：语法[@return description]
用description本文添加“返回”部分，该文本应描述值的返回类型和容许范围
3.9-@see(1.0)：语法[@see reference]
该标记是一个相对复杂的标记，添加“参见”标题，其中有指向reference的链接或者文本项，文档注释可包含任意数目的@see标记，它们都分组在相同的标题下，@see有三种格式：
3.9.1-@see “string” 注：该形式在JDK 1.2中没有用，它不打印引用文本
为string添加文本项，不产生链接，string是通过该URL不可用的书籍或者其他信息引用，Javadoc通过查找第一个字符为双引号（”）的情形来区分它前边的情况，比如：
@see "这是Java教材，主要是提供给初学者"上边的注释将会生成：
"这是Java教材，主要是提供给初学者"
3.9.2-@see html中的a标签
添加URL#value定义的链接，其中URL#value是相对URL或者绝对URL，JavaDoc工具通过查找第一个字符小写符号（<）区分它与其他情况，比如：
@see <a href="page.html#section">测试规范超链接</a>上边的注释将会生成：
3.9.3-@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 通常不严格，并允许在不产生歧义时使用点号，但是它将显示警告。
3.9.4-@see标记的搜索次序
JavaDoc将处理出现在源文件（.java）、包文件（package.html）或概述文件（overview.html）中的@see标记，在后两种文件中，必须完全限定使用@see提供的名字，在源文件中，可指定全限定或部分限定的名字，@see的搜索顺序为：
- 当前类或接口
- 任何包含类和接口，先搜索最近的
- 任何父类和超接口，先搜索最近的
- 当前包
- 任何导入包、类和接口，按导入语句的次序搜索
3.10-@since(1.1)：语法[@since since-text]
用since-text指定的内容给生成文档添加“Since”标题，该文本没有特殊内部结构，该标记表示该改变或功能自since-text所指定的软件件版本后就存在了，例如：@since JDK 1.4
3.11-@serial(1.2)：语法[@serial field-description]
用于缺省的可序列化域的文档注释中，可选的field-description增强了文档注释对域的描述能力，该组合描述必须解释该域的意义并列出可接受值，如果有需要描述可以多行，应该对自Serializable类的最初版本之后添加的每个可序列化的域添加@since标记。
3.12-@serialField(1.2)：语法[@serialField field-name field-type field-description]
简历Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档，应该对每个ObjectStreamField使用一个@serialField标记
3.13-@serialData(1.2)：语法[@serialData data-description]
data-description建立数据（尤其是writeObject方法所写入的可选数据和Externalizable.writeExternal方法写入的全部数据）序列和类型的文档，@serialData标记可用于writeObject、readObject、writeExternal和readExternal方法的文档注释中
3.14-@version(1.0)：语法[@version version-text]
当使用-version选项时用version-text指定的内容给生成文档添加“版本”子标题，该文本没有特殊内部结构，文档注释最多只能包含一个@version标记。
3.15-{@code}(1.5)：语法[{@code text}]
该标签等同于<code>{@literal}</code>，里面可以直接过滤掉HTML的标签，可以不用<和>来显示（<和>），在这个代码块里面的text部分，可以直接书写代码，即使使用了<b>Hello</b>，在HTML里面也不会识别成为加粗的Hello，而还是原来的代码段<b>Hello</b>的格式输出
3.16-{@docRoot}(1.3)：语法[{@docRoot}]
代表相对路径生成的文件的（目标）的根从任何产生的网页目录，当您要包括如版权页或公司徽标文件的时候它是有用的，你要引用所生成的网页，链接从每个页面底部的版权页面是常见的。（@docRoot将标记可用于在命令行，并在两个文档注释：这个标记是有效的，在所有文档注释：概述、包装类、接口、构造、方法和领域，包括任何标记文本的一部分（如@return ，@param和@deprecated的使用）。
比如：
/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
**/3.17-{@inheritDoc}(1.4)：语法[{@inheritDoc}]
继承（拷贝）文档从最近的“继承类或可执行的接口”到当前在这个标签的位置的文档注释内容，这使您可以编写更多与继承相关的一般性文档
下边的情况比较适合：
在一个方法的主要描述块，在这种情况下，主要描述是整个继承树结构里面的类和接口的一个拷贝。
在文本参数返回的@return @param和@throws等方法标记，在这种情况下，文本标记是整个层次结构里面标签的拷贝。
3.18-{@linkplain}(1.4)：语法[{@linkplain package.class#member label}]
和{@link}类似，除非链接的label是用普通文本的格式显示的，当文本是普通文本的时候该标签就能够起作用，例如：
Refer to {@linkplain add() the overridden method}这个会显示成：
Refer to the overridden method
3.19-{@value}(1.4)：语法[{@value package.class#field}]
主要用来显示静态字段的值：
/**
* The value of this constant is {@value}
**/
public static final String SCRIPT_START = "script";结果是： The value of this constant is "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;
}
}