编写程序时，应该说必须为程序添加一些注释，用来说明某段代码的作用，或者说明某个类的用途、某个方法的功能，以及该方法的参数和返回值的数据类型及其意义等。
添加注释主要考虑以下三个方面：

  • 永远不需要相信自己的理解力和记忆力，随着代码量的增加代码会越来越难阅读，添加注释实际上是添加编码当时的想法。
  • 可读性第一，效率第二，横向考虑整个团队的发展，个人的代码一定会有其他人阅读的，而合适的注释是个人或者其他人阅读代码成本最低的一个途径。
  • 代码即文档，其实就是说代码规范，好的代码规范下的代码可读性非常高，有一句话叫代码自解释，当代码自己能解释自己的意愿的时候可读性就有了。

代码注释分类

  • 单行注释 用双斜线 ”//” 表示
  • 多行注释 用 /------------------/ 表示
  • 文档注释 用 /**-----------------*/ 表示【用javadoc为自己的代码生成API文档用】
public class CommentTest
{
    /*
    这里面的内容全部是多行注释
    Java语言真的很有趣，
    */
    public static void main(String[] args)
    {
        // 这是一行简单的注释
        System.out.println("Hello World!");
        // System.out.println("这行代码被注释了，将不会被编译、执行!");
    }
}
  1. API文档用于说明类、方法、成员变量的功能，因此javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前d注释，忽略其他地方的注释，并且javadoc工具默认只处理以public或protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释
  2. API文档类似于产品说明书，默认只介绍暴露的供用户使用的部分。如果开发者确实想看到private修饰的内容，则在使用javadoc工具时增加-private选项即可

生成源码文件API文档

package davieyang;
/**
 * Description:
 * 网站: <a href='javascript:void(0)'>
public class JavadocTest
{
    /**
     * 简单测试成员变量
     */
    protected String name;
    /**
     * 主方法，程序的入口
     */
    public static void main(String[] args)
    {
        System.out.println("Hello World!");
    }
}
package scc;
/**
 * Description:
 * 网站: <a href='javascript:void(0)'>
public class Test
{
    /**
     * 简单测试成员变量
     */
    public int age;
    /**
     * Test类的测试构造器
     */
    public Test()
    {
    }
}
package NBwang;

/**
 * Description:
 * 网站: <a href='javascript:void(0)'>
public class JavadocTagTest
{
    /**
     * 一个得到打招呼字符串的方法。
     * @param name 该参数指定向谁打招呼。
     * @return 返回打招呼的字符串。
     */
    public String hello(String name)
    {
        return name + "，你好！";
    }
}
javadoc -d apidoc -windowtitle 测试javadoc -doctitle 学习javdoc工具测试API文档 -header 我醉欲眠卿且去 *Test.java

Java面向对象系列[v1.0.0][javadoc]_经验分享

  • -d 指定生成API文档在本地的存储路径
  • -windowtitle: 指定一个字符串，设置API文档的浏览器窗口标题
  • -doctitle: 指定一个HTML格式的文本，用于指定概述页面标题
  • -header: 指定一个HTML格式的文本，包含每个页的页眉
  • 除此之外还可以使用javadoc -help来查看大量的javadoc选项

源码中的一些标记也会展示在API文档中：
例如​​​@author/@version/@deprecated/@param/@return/@see/@exception/@throws​​​等等
javadoc默认不会提取@author和@version，这两个特殊的标记需要在执行命令的时候以参数的形式指明

javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadoc -header davieyang页眉 -version -author *Test.java

生成package的API文档

新建两个用英文命名的文件夹，然后将上述3段代码放在3个文件中，将其分撒在两个文件夹内，然后每个文件夹里添加对包的表述文档，该文档需要html格式，如下所示

<!DOCTYPE html>
<html>
<head>
    <meta name="author" content="davieyang.D.Y(davieyang.blog.csdn.net)" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title> davieyang包描述 </title>
</head>
<body>
davieyang包描述
</body>
</html>
<!DOCTYPE html>
<html>
<head>
    <meta name="author" content="scc.D.Y(davieyang.blog.csdn.net)" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title> scc包描述 </title>
</head>
<body>
scc包描述
</body>
</html>

然后再两个文件夹所在路径执行命令：

javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc工具 -header davieyang页眉 -version -author davieyang scc