java半碳_Javadoc详解

Javadoc是由源代码文件生成的HTML文件，它能清晰地解释一个类、方法的作用，

Javadoc可以分为三种：

类注释

方法注释

字段注释

包注释

在讲这三种Javadoc之前，我们先说一些基本知识

格式

Javadoc抽取以/**开头，以*/结尾的注释中的信息，不过仅限于：

模块

包

公共类和接口

公共的和受保护的字段

公共的和受保护的构造器及方法

在/**和*/之间插入我们需要写的东西，以@开头，如@author，@since等，在一些这样的标记中，也可以使用HTML修饰符，如和、和等

类注释

类注释必须放在import语句之后，类定义之前。如下：

import java.lang.String;

/**

* 这个类的用途不是打印Hello World

*/

public class HelloWorld

{

public static void main(String[] args)

{

StringBuilder a = new StringBuilder("I do not want to say 'Hello World'");

System.out.println(a);

}

}

生成这个类的Javadoc效果如下，生成方法后面再说：

方法注释

方法注释要放在所描述的方法之前，为了对方法的描述更加清晰，可能使用以下标记：

@param是对每一个参数的解释

@return是对返回部分的解释

@throws是可能抛出的异常的解释

/**

* 重复输出Hello World

* @param times 重复次数

*/

public HelloWorld(int times)

{

String a = "Hello World";

System.out.println(a.repeat(times));

}

生成结果如下：

字段注释

是对字段建立的文档，如

/**

* The answer to life, the universe and everything

*/

public final int answer = 42;

生成结果如图：

包注释

包注释是对一个包的注释，它往往放在一个单独的package-info,java文件中，它只允许有一个文档注释/**和*/和一个package语句组成，这里能使用@author、@version等标记，如下所示：

/**

* 常用工具包

* @author 碳烤黄蜂

* @version 1.0.0

*/

package Tools;

生成方法

使用

javadoc 文件名

方式生成Javadoc，如果报这个错误：

错误: 编码GBK的不可映射字符

则改成这样：

javadoc -encoding UTF-8 文件名

改变提取目录

按照上面的方法生产的文档和程序在同一目录下，为了便于查找和管理文档，我们可以改变它的生成路径：

javadoc -d 文档目录 文件名

提取多个

如果要一次提取多个包或文件的话，只需：

javadoc -d 文档目录 文件名1 文件名2 ...