Java嵌入式文档

在快速开发背景下的程序构建，合作变得越来越重要，而合作质量很重要的一个衡量标准，就是你的parterner要读得懂你的程序，因此，好的程序不仅可读性要好，文档也要写的好。其实不仅是合作伙伴，自己写的程序再回过头看，如果没有良好的参考及书写习惯，阅读过程也是十分痛苦的！
本篇博文主要讲解一下java中常见的嵌入式文档。
嵌入式文档通过jdk自带的javadoc来解析，所有的javadoc命令都只能在/**注释中出现，结束于*/，使用javadoc的方式主要有两种：嵌入HTML，或使用“文档标签”。独立文档标签是一些以“@”开头的命令，紧贴*放在注释行的最前面；行内文档标签则可以出现在javadoc的任何地方，他们也是以“@”开头，但要置于花括号内(注意，行内文档不会单列一行)。最终javadoc将会生成一个HTML文件。（注意，javadoc只能为public和protected成员生成注释文档，private和包内可访问成员的注释会被忽略掉。）
共有三种类型的注释文档，分别用于类、域、方法前，可以使用的javadoc标签也稍有不同，比如用于类的注释就没有@param等
下面来详细介绍一下嵌入式HTML与文档标签。
嵌入式HTML
主要目的是对代码进行格式化，可以充分利用HTML代码，例如：

  /**
  *
  *System.out.println(new Data());
  *
  */

但要注意，javadoc也有自己的格式，因此有些标签如

之类的会被javadoc舍弃。

文档标签
文档标签有很多，并且随着jdk更新，javadoc也会更新，下面介绍几种常用的文档标签：
1.@see ：引用其他类
如 @see DataBaseHelper
2.{@doRoot}：该文档产生到文档根目录的相对路径，用于文档树页面的显式超链接。
3.version：显示版本信息
如@version 1.0
4.@author：显示作者信息
如@author FounderWatts
5.@param：用于方法文档，描述参数信息
如@param parm used to do .....
6.@return：用于方法文档，描述返回信息
如@return test
7.@throws：用于方法文档，描述方法抛出的异常信息
如@throws IOException
8.@deprecated：表示已经被弃用，不建议使用
如：@deprecated
例子：
Main.java

/**
 * 
 * @author Founder
 * @version 1.0
 * @see DataBaseHelper
 * This is a DataBaseHelper class
 * 
 */
public class Main{
    /**
     * 
     * @param parm used to do .....
     * @return test
     */
    public String test(int parm){
        return "test";
    }
}

DataBaseHelper.java

import java.io.IOException;

/**
 * 
 * @author Founder
 * {@code public class DataBaseHelper}
 *
 */
public class DataBaseHelper {

    /**
     * 
     * @throws IOException
     * @deprecated
     */
    public void helper() throws IOException{

    }
}

生成的网页文件还比较炫，截图看一下：