java文档注释与javadoc

在编写程序中，我们往往为代码文档所头疼。如果文档与代码是分离的，那么在每次修改代码的时候，都要去修改响应的文档。

在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 该方法已过时



四、为了帮助大家更好的理解，下来我找来J***A的源代码，来学习学习

大家可以把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，小伙伴们，你们达到了吗？