Java文档注释（利用javadoc生成HTML文档）

最新推荐文章于 2023-09-09 22:33:54 发布

JuBlog

最新推荐文章于 2023-09-09 22:33:54 发布

阅读量2.8k

点赞数

分类专栏： Java学习笔记文章标签： java html javadoc

本文链接：https://blog.csdn.net/weixin_42041195/article/details/109546099

版权

Java学习笔记专栏收录该内容

12 篇文章 0 订阅

订阅专栏

1. 在代码中使用文档注释

Java 程序员在开发的过程中，或多或少都会有查阅 API（Application Programming Interface）文档的需求，层次分明的 API 文档给 Java 开发带来了极大的便利。那么，我们有没有办法给自己的程序，也“编写”这样一个结构化的文档呢？答案当然是肯定的！

JDK 包含一个很有用的工具，叫做 javadoc, 它可以由 Java 源文件生成一个HTML文档，只需要在源代码中添加相对应的以 /**开始，并以 */ 结束的注释，然后利用 javadoc 指令，就可以为自己的程序生成类似 Java API 的文档！

这是一种很好的方式，因为这种方式可以将代码与注释保存在一个地方。如果将文档存人一个独立的文件中，就有可能会随着时间的推移，出现代码和注释不一致的问题。然而，如果文档注释与源代码在同一个文件中，在修改源代码的同时，重新运行 javadoc 就可以轻而易举地保持两者的一致性。

编写Java程序时，需为以下部分插入文档注释：

包
公有类与接口
公有的和受保护的构造器及方法
公有的和受保护的域

2. 类注释

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

import com.jujunjian.demo.Person;

/**
 * Describe your class
 * 
 * @version 1.0 2020-11-07
 * @author JuJunjian
 */

public class Student extends Person {

}

3. 方法注释

每一个方法注释必须放在所描述的方法之前。对于方法而言，还可以使用下面的标记：

@param：对方法的参数变量进行描述。
@return：对方法的返回值进行描述。
@throws：用于表示这个方法有可能抛出异常。

/**
* 一个寻找列表中元素（Integer类型）最大值的方法
* @param list 搜索最大值的列表
* @return max list中的最大值
*/
public Integer getMax(List<Integer> list){
	Integer max = 0;
	// 方法的具体实现
	return max;
}

4. 域注释

只需要对公有域（通常指的是静态常量）建立文档。例如：

/**
* The "Hearts" card suit
*/
public static final int HEARTS = 1;

5. 通用注释

@author 姓名
@version 版本
@since 文本

这个标记将产生一个“ since” （始于）条目。这里的 text 可以是对引人特性的版本描述。例如，©since version 1.7.10
@deprecated 文本

这个标记将对类、方法或变量添加一个不再使用的注释。
@see/@link 引用

通过 @see 和 @link 标记，可以使用超级链接，链接到 javadoc 文档的相关部分或外部文档。

6. 包与概述注释

可以直接将类、方法和变量的注释放置在 Java 源文件中，只要用 /** . . . */ 文档注释界定就可以了。但是，要想产生包注释，就需要在每一个包目录中添加一个单独的文件。

可以有如下两个选择：

提供一个以 package.html 命名的 HTML 文件。在标记<body>...</body> 之间的所有文本都会被抽取出来.
提供一个以 package-info.java命名的 Java 文件。这个文件必须包含一个初始的以 /** 和 */ 界定的 Javadoc 注释，跟随在一个包语句之后。它不应该包含更多的代码或注释。
还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html 的文件中，这个文件位于包含所有源文件的父目录中。标记<body>... </body>间的所有文本将被抽取出来。当用户从导航栏中选择“Overview” 时，就会显示出这些注释内容。

7. 注释的抽取

这里，假设 HTML 文件将被存放在目录 docDirectory 下，执行以下步骤：

切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档，例如com.horstmann.corejava，就必须切换到包含子目录com的目录（如果存在 overview.html 文件的话，这也是它的所在目录)。
如果是一个包，应该运行命令:
javadoc -d docDirectory nameOfPackage
对于多个包生成文档，运行:
javadoc -d docDirectory nameOfPackage1 nameOfPackage2…
如果文件在默认包中，就应该运行：
javadoc -d docDirectory *.java

如果省略了 -d docDirectory 选项，那 HTML 文件就会被提取到当前目录下。这样有可能会带来混乱，因此不提倡这种做法。

在提取文档注释时经常需要指定编码方式，加上 -encoding charset 可以指定编码方式（charset处填写编码方式，如 UTF-8）。例如：