这次学习笔记的内容:
- Java 的 3 种注释符:单行注释、多行注释、文档注释
- javadoc工具导出文档注释
注释
注释相当于一份代码的说明文档,写注释是为了增强程序的可读性,有利于软件的维护、团队协作、软件升级和修改等等。
单行注释和多行注释
在 Java 语言中,单行注释符是 //,多行注释符是 /**/。
public class CommentTest
{
/*
这里的内容是多行注释
Java 语言真有趣
*/
public static void main(String[] args)
{
// 这是一行注释
System.out.println("Hello World!");
// System.out.println("被注释的代码不会执行");
}
}
添加注释也是调试程序的一个方法,把你认为可能有问题的代码注释掉,然后运行程序,如果程序正常运行,那就说明程序问题出现在注释掉的代码部分。如果程序没有正常运行,那就说明程序问题不出现在注释掉的代码部分,而是在其他代码部分。不管怎样,都能减少排查范围。
官方 API 文档
Oracle 为 Java 的基础类提供了一份 API 文档,用于描述这些类的作用和使用方法。例如 Java SE 11 API 文档的下载地址:Java Development Kit 11 Documentation
打开 docs 目录中的 index.html:
某个类的文档描述:
我们也可以为自己编写的程序添加文档注释并制作 API 文档,只要在源代码中添加合适的文档注释,然后通过 javadoc 工具将这些文档注释提取成一份系统的 API 文档。
javadoc 工具
javadoc 工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释,忽略其他地方的注释,而且默认只处理以 public 或 protected 修饰的(因为只有 public 和 protected 才希望暴露细节)。如果要提取 private 修饰的内容,则可以在使用 javadoc 命令时添加 -private 选项。
javadoc 基本用法:javadoc 选项 Java源文件|包
常用的选项:
- -d <directory>:指定生成的 API 文档的存放目录。
- -windowtitle <text>:API 文档的浏览器窗口标题。
- -doctitle <html-code>:指定一个 HTML 格式的文本,用于设置概述页面的标题。
- -header <html-code>:指定一个 HTML 格式的文本,包含每个页面的页眉。
- -encoding <charset>:javadoc 如何用何种字符集解释文档注释的内容,例如 utf8。
只有对处于多个包下的源文件来生成 API 文档时,才有概述页面。
利用 javadoc 标记生成更详细的内容,常用的 javadoc 标记:
- @author:java 程序的作者
- @version:源文件的版本
- @deprecated:不推荐使用的方法
- @param:方法的参数说明信息
- @return:方法的返回值说明信息
- @see:"参见",用于指定交叉从参考的内容
- @exception:抛出异常的类型
- @throws:与 @exception 同义
这些标记的使用有位置限制,出现在类或接口文档注释中的可以有 @see、@deprecated、@author 和 @version;出现在方法或构造器文档注释中的可以有 @see、@deprecated、@param、@return、@throws 和 @exception;出现在成员变量的文档注释中的可以有 @see 和 @deprecated。
javadoc 工具默认不提取 @author 和 @version,如果需要,则添加 -author 和 -version 选项。
文档注释
文档注释以 /** 开头,以 */ 结尾,每行用 *
javadoc 使用
在当前目录下创建两份源文件,内容如下:
JavadocTest.java
package lee;
/**
* Description:
* This program is protected by copyright laws.<br>
* Program Name: <br>
* Date: <br>
* @author liwu 131323@qq.com
* @version 5.0
*/
public class JavadocTest
{
/**
* 简单测试成员变量
*/
protected String name;
/**
* 主方法,程序的入口
*/
public static void main(String[] args)
{
System.out.println("Hello World!");
}
}
Test.java
package yeeku;
/**
* Description:
* This program is protected by copyright laws.<br>
* Program Name: <br>
* Date: <br>
* @author liwu 131323@qq.com
* @version 5.0
*/
public class Test
{
/**
* 简单测试成员变量
*/
public int age;
/**
* Test类的测试构造器
*/
public Test()
{
}
}
在当前目录下打开命令行窗口,执行:
javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具的测试 API 文档 -header 我的类 -encoding utf8 *Test.java
* 表示通配符。打开 apidoc/index.html:
可以看到包的说明是空的,这里的内容必须由另外一个 HTML5 文件提供包注释,这个文件称为包描述文件,文件名通常为 package.html,并与该包下所有的 Java 源文件放在一起,javadoc 工具会自动寻找对应的包描述文件,并提取该包描述文件中的 <body> 元素里的内容,作为该包的描述信息。
在当前目录下创建 lee 和 yeeku 两个目录,并把 JavadocTest.java 放到 lee 目录下,Test 放到 yeeku 目录下,然后分别创建 package.html:
接着在命令行窗口执行命令:
javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadoc工具的测试API文档 -header 我的类 -version -author -encoding utf8 lee yeeku
打开 apidoc/index.html: