在编写程序中，我们往往为代码文档所头疼。如果文档与代码是分离的，那么在每次修改代码的时候，都要去修改响应的文档。
在java中，你可以为你的代码加上特别的注释，针对方法变量类等等可以加上一些标签。
javadoc是一个提取注释的工具，它在代码中查找特殊的注释标签，然后解析这些标签生成对应的文档。
javadoc输出的是一个HTML文件，就如同我们大家经常使用的java API文档一样，浏览非常的方便。
一、一共有三种类型的注释文档。分别对应注释位置后面的 类， 变量， 方法。
举一个简单的例子
//** A Class comment */
public class Documentation{
/** A field comment */
public int i;
/** A method comment */
public void f() {}
}
二、另外由于javadoc生成的是HTML文档，所以你还可以再注释中加入HTML标签。要注意的一点是不要加入标题标签<h1>或<hr>，
因为javadoc会插入自己的标题，所以为了防止冲突，不要加它们。
三、其他的一些标签。
在三种类型的注释文档中，我们除了可以编写注释外，还可以加入一些标签，使得注释内容更加详细。
有以下几种标签：
1.@see 显示参考类
2.{@link package.class#member label} 链接到另一个类
3.{@docRoot}在文档根目录树下，表现出显式链接
4.{@inheritDoc} 继承父类的文档显示到注释中
5.@varison 当前版本
6.@author 作者，可以包含e-mal地址或其他信息
7.@sice 程序代码最早使用的版本
8.@param 参数
9.@return 返回值
10.@throws 抛出异常
11.@Deprecated 该方法已过时
四、为了帮助大家更好的理解，下来我找来JAVA的源代码，来学习学习
大家可以把API文档与源码对照，来观察各个标签。
①. String类的声明注释
/**
* An immutable sequence of characters/code units ({@code char}s). A
* {@code String} is represented by array of UTF-16 values, such that
* Unicode supplementary characters (code points) are stored/encoded as
* surrogate pairs via Unicode code units ({@code char}).
*
* <a name="backing_array"><h3>Backing Arrays</h3></a>
* This class is implemented using a char[]. The length of the array may exceed
* the length of the string. For example, the string "Hello" may be backed by
* the array {@code ['H', 'e', 'l', 'l', 'o', 'W'. 'o', 'r', 'l', 'd']} with
* offset 0 and length 5.
*
* <p>Multiple strings can share the same char[] because strings are immutable.
* The {@link #substring} method <strong>always</strong> returns a string that
* shares the backing array of its source string. Generally this is an
* optimization: fewer character arrays need to be allocated, and less copying
* is necessary. But this can also lead to unwanted heap retention. Taking a
* short substring of long string means that the long shared char[] won't be
* garbage until both strings are garbage. This typically happens when parsing
* small substrings out of a large input. To avoid this where necessary, call
* {@code new String(longString.subString(...))}. The string copy constructor
* always ensures that the backing array is no larger than necessary.
*
* @see StringBuffer
* @see StringBuilder
* @see Charset
* @since 1.0
*/
public final class String implements Serializable, Comparable<String>, CharSequence {
②.String的一个构造方法
/**
* Converts the byte array to a string, setting the high byte of every
* character to the specified value.
*
* @param data
* the byte array to convert to a string.
* @param high
* the high byte to use.
* @throws NullPointerException
* if {@code data == null}.
* @deprecated Use {@link #String(byte[])} or {@link #String(byte[], String)} instead.
*/
@Deprecated
public String(byte[] data, int high) {
③.lastIndexOf方法
/**
* Searches in this string for the last index of the specified string. The
* search for the string starts at the end and moves towards the beginning
* of this string.
*
* @param string
* the string to find.
* @return the index of the first character of the specified string in this
* string, -1 if the specified string is not a substring.
* @throws NullPointerException
* if {@code string} is {@code null}.
*/
public int lastIndexOf(String string) {
// Use count instead of count - 1 so lastIndexOf("") returns count
return lastIndexOf(string, count);
}
五、javadoc在Eclipse里的使用
使用eclipse生成文档（javadoc）主要有三种方法：
1，在项目列表中按右键，选择Export（导出），然后在Export(导出)对话框中选择java下的javadoc，提交到下一步。
在Javadoc Generation对话框中有两个地方要注意的：
javadoc command:应该选择jdk的bin/javadoc.exe
destination:为生成文档的保存路径，可*选择。
按finish(完成)提交即可开始生成文档。
2，用菜单选择：File->Export(文件－>导出)，
剩下的步骤和第一种方法是一样的。
3，选中要生成文档的项目，然后用菜单选择，
Project->Generate Javadoc直接进入Javadoc Generation对话框，剩余的步骤就和第一种方法在Javadoc Generation对话框开始是一样的。
需要注意的一点：javadoc生成中文文档乱码的问题（如果大神只写英文文档的话可略过）
4.我们需要设置额外的命令 -encoding UTF-8 -charset UTF-8
意思是以UTF-8的格式读取源码，以UTF-8的形式输出文档
java是开源的，网上应该可以搜到源代码的。通过阅读源代码呢，我们不仅可以学习写代码，而且还可以学习写注释。
有人说一般情况下，一个程序的注释不能少于该程序的1/3，小伙伴们，你们达到了吗？