Java 学习之路 02--注释

friEnd`

已于 2022-06-16 00:40:58 修改

阅读量517

点赞数

分类专栏： Java学习文章标签：学习

于 2022-06-02 16:44:43 首次发布

本文链接：https://blog.csdn.net/shawdow_bug/article/details/125099972

版权

Java学习专栏收录该内容

4 篇文章 0 订阅

订阅专栏

这次学习笔记的内容：

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：