JavaDoc 文档生成

JavaDoc

很多程序对 Javadoc 都不重视，认识不到 Javadoc 的作用，很多人都是这样认为的：“我只要写好功能就够了，写 Javadoc 太浪费时间，也没啥作用，还不如用写 Javadoc 的时间再多些个功能呢！”，我们知道注释是为了解释代码的作用的，是为了将来给自己或者别人快速了解代码的，在方法内一般用行注释//的比较多，是针对一小块代码做出解释的，而 Javadoc 的作用是针对整个方法或者整个类做一个简要的概述的，使得别人不通过看具体方法代码就能知道某个方法或者某个类的作用和功能。写了 Javadoc 的在别人使用到类时，将鼠标悬停到类上或者方法上，Javadoc 会以提示信息显示出来，这样开发者在跳进源代码中就能知道类或者方法的作用。说到这里可能还是有很多人不能认同这种观点，还是认识不到 Javadoc 的作用。我们看一下Spring 框架，随便打开一个文件可以看到一般注释内容都要比代码量多，有的时候注释量占整个文件内容的2/3。有人还是认为 Spring 是大框架，每个 Java 项目都在用他们写的好事应该的，我们公司自己的项目就我们公司几个人看，没必要花时间去写多余的Javadoc，那你是不是该这么认为了 Spring 大厂中的顶尖大牛都这么做，我们小菜鸟是不是对自己要求更严格一些，向大牛去学习呢？！假如在公司A程序员写了Javadoc，B程序员只写功能不写 Javadoc 不写注释，那么一般会认为A程序员会比B程序员做的好。认识不到 Javadoc 的作用就像认识不到设计模式的作用一样，很多人都认识不到设计模式的作用，认为将简单问题复杂化，你看一下每个大框架都会用到多种设计模式，如果只知道写增删改查，再工作几年仍然不会有提高。

参考 ：Javadoc 使用详解

简介

  • Java 代码注释分为 ：单行注释、多行注释、文档注释也称为说明注释

    • 单行注释形式 : //

    • 多行注释形式 ：/* */

    • 文档注释形式 ：/** */

  • javadoc 命令是用来将文档注释内容生成类似 jdk 帮助文档格式的 API 文档，允许你在程序中嵌入关于程序的信息。你可以使用 javadoc 工具软件来生成信息，并输出到HTML文件中。

文档注释使用的标签

  • javadoc 工具软件识别以下标签：

    标签 描述 示例
    @author 标识一个类的作者 @author description
    @deprecated 指名一个过期的类或成员 @deprecated description
    指明当前文档根目录的路径 Directory Path
    @exception 标志一个类抛出的异常 @exception exception-name explanation
    从直接父类继承的注释 Inherits a comment from the immediate surperclass.
    插入一个到另一个主题的链接
    插入一个到另一个主题的链接，但是该链接显示纯文本字体 Inserts an in-line link to another topic.
    @param 说明一个方法的参数 @param parameter-name explanation
    @return 说明返回值类型 @return explanation
    @see 指定一个到另一个主题的链接 @see anchor
    @serial 说明一个序列化属性 @serial description
    @serialData 说明通过writeObject( ) 和 writeExternal( )方法写的数据 @serialData description
    @serialField 说明一个ObjectStreamField组件 @serialField name type description
    @since 标记当引入一个特定的变化时 @since release
    @throws 和 @exception标签一样. The @throws tag has the same meaning as the @exception tag.
    显示常量的值，该常量必须是static属性。 Displays the value of a constant, which must be a static field.
    @version 指定类的版本 @version info

    • @version 只能用于类上注释，代码版本

    • @since 一般指最低支持的 jdk 版本

    • @exception、@throws 抛出的异常

    • @param 方法参数

    • @return 返回值

    • {@link} {@link 包名.类名#方法名(参数类型)} 用于快速链接到相关代码

    • {@value} 显示常量的值，该常量必须是static属性。

    • @code： {@code text} 将文本标记为code

    • {@code text} 会被解析成<code>text <\code>
      将文本标记为代码样式的文本，在code内部可以使用 < 、> 等不会被解释成html标签, code标签有自己的样式

      一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。

    • 详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用html标签，如<p>、<pre>、<a>、<li>等标签， 通常详细描述都以段落p标签开始。
      详细描述和概要描述中间通常有一个空行来分割

    • 注意 ：

      • 当 {@link }用于连接到方法时 ：包名.类名#方法名(参数类型)，方法名前必须是 # 号，用法 ：

测试代码提供

  • 提供用于生成 javadoc 文档的代码如下,只运用了部分标签演示

    import org.apache.tomcat.util.buf.HexUtils;

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

/**
 * @author yuanhy
 * @version 1.0
 * @date 2020/10/04
 */
public class Test01 {
    /**
     * 默认测试数据 {@value}
     */
    public static final String DATA = "测试 javadoc";

    /**
     * 这是程序运行的入口
     *
     * @param args 字符串数组
     */
    public static void main(String[] args) {
        String response = responseInput(DATA);
        System.out.println("response:" + response);
    }

    /**
     * 返回输入信息
     *
     * @param input 输入的信息
     * @return {@link String}
     * @see {@link String} 字符串
     * @deprecated 已过期
     */
    public static String responseInput(String input) {
        return input;
    }

    /**
     * 计算消息摘要
     * <p>
     * <pre>
     *         {@code
     *          演示使用 {@link Test01#generateHash(String)}
     *          String message = "测试生成 JavaDoc";
     *          String response = Test01.generateHash(message);
     *         }
     *     </pre>
     * </p>
     *
     * @param message 待计算消息摘要数据
     * @return 16 进制摘要数据
     * @exception NoSuchAlgorithmException 不支持算法
     * @throws NoSuchAlgorithmException 不支持算法
     */
    public static String generateHash(String message) throws NoSuchAlgorithmException {
        MessageDigest messageDigest = MessageDigest.getInstance("MD5");
        byte[] hashResult = messageDigest.digest(message.getBytes());
        return HexUtils.toHexString(hashResult);
    }
}

生成 JavaDoc

  • cmd 生成

    引用 ： Java命令行命令详解

    • 编码报错：是因为我的命令行-docencoding 报的错，改为-encoding

      C:\Program Files\Java\jdk1.8.0_111\bin>javadoc D:\data\csims\ssltcp\src\test\java\Test01.java -docencoding UTF-8 -charset UTF-8 -windowtitle "测试 CMD 生成 JavaDoc" -link https://docs.oracle.com/javase/8/docs/api/ -d D:\data\JavaDoc\cmdhtml\
正在加载源文件D:\data\csims\ssltcp\src\test\java\Test01.java...
D:\data\csims\ssltcp\src\test\java\Test01.java:17: 错误: 编码GBK的不可映射字符
     * 杩欐槸绋嬪簭杩愯鐨勫叆鍙?
                    ^
D:\data\csims\ssltcp\src\test\java\Test01.java:19: 错误: 编码GBK的不可映射字符
     * @param args 瀛楃涓叉暟缁?
                          ^
D:\data\csims\ssltcp\src\test\java\Test01.java:29: 错误: 编码GBK的不可映射字符
     * @param input 杈撳叆鐨勪俊鎭?
                           ^
D:\data\csims\ssltcp\src\test\java\Test01.java:31: 错误: 编码GBK的不可映射字符
     * @see String 瀛楃涓?
                       ^
D:\data\csims\ssltcp\src\test\java\Test01.java:32: 错误: 编码GBK的不可映射字符
     * @deprecated 宸茶繃鏈?
                       ^
D:\data\csims\ssltcp\src\test\java\Test01.java:50: 错误: 编码GBK的不可映射字符
     * @param message 寰呰绠楁秷鎭憳瑕佹暟鎹?

      修改命令行编码 : chcp 65001

      chcp 命令

    • 在相应的目录打开 index.html 就可查看效果

  • idea 生成

    • 以 Test01.java 文件为例，选中 Test01.java 文件，Tools --> Generate JavaDoc

    • 在 Generate JavaDoc scope 域选择 File

    • 在 Locale 域填写 : zh_CN

    • 在 Other command line arguments 域填写 : -encoding UTF-8 -charset UTF-8

      • -encoding : 表示源码基于 UTF-8 编码
      • -charset : 表示在处理并生成 JavaDoc 超文本时使用的字符集也是以 UTF-8 为编码
      • -encoding UTF-8 -charset UTF-8 -windowtitle "测试API JavaDoc 生成" -link https://docs.oracle.com/javase/8/docs/api/
        • 第三个参数 -windowtitle 表示生成的 JavaDoc 超文本在浏览器中打开时，浏览器窗口标题栏显示的文字内容；
        • 第四个参数 -link 很重要，它表示你生成的 JavaDoc 中涉及到很多对其他外部 Java 类的引用，是使用全限定名称还是带有超链接的短名称，举个例子，我创建了一个方法 public void func(String arg)，这个方法在生成 JavaDoc 时如果不指定 -link 参数，则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg)，因为 String 这个类对我自己实现的类来讲就是外部引用的类，虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数，则 javadoc.exe 在生成 JavaDoc 时，会使用 String 这样的短名称而非全限定名称 java.lang.String，同时自动为 String 短名称生成一个超链接，指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件，在这个文本文件中包含了所有外部引用类的全限定名称，因此生成的新 JavaDoc 不必使用外部引用类的全限定名，只需要使用短名称，同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。每个 JavaDoc 都会在根目录下有一个 package-list 文件，包括我们自己生成的 JavaDoc。

    • 效果 ：

      • 类 Test01

        public class Test01
extends Object

        • 版本:

          1.0

        • 作者:

          yuanhy

          字段概要

          限定符和类型 字段和说明
          static String DATA默认测试数据 "\u6d4b\u8bd5 javadoc"

          构造器概要

          构造器和说明
          Test01()

          方法概要

          限定符和类型 方法和说明
          static String generateHash(String message)计算消息摘要 演示使用 {@link Test01#generateHash(String)} String message = "测试生成 JavaDoc"; String response = Test01.generateHash(message);
          static void main(String[] args)这是程序运行的入口
          static String responseInput(String input)已过时。 已过期 
          ### 从类继承的方法 java.lang.[Object](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true)

```
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
```

          字段详细资料

          • DATA

            public static final String DATA

            默认测试数据 "\u6d4b\u8bd5 javadoc"

          构造器详细资料

          • Test01

            public Test01()

          方法详细资料

          • main

            public static void main(String[] args)

            这是程序运行的入口

            • 参数:

              args - 字符串数组

          • responseInput

            public static String responseInput(String input)

            已过时。 已过期

            返回输入信息

          • generateHash

            public static String generateHash(String message)
                           throws NoSuchAlgorithmException

            计算消息摘要

                      演示使用 {@link Test01#generateHash(String)}
          String message = "测试生成 JavaDoc";
          String response = Test01.generateHash(message);

            • 参数:

              message - 待计算消息摘要数据

            • 返回:

              16 进制摘要数据

            • 抛出:

              NoSuchAlgorithmException - 不支持算法

              NoSuchAlgorithmException - 不支持算法

posted @ 2020-10-07 22:35  袁胡悦  阅读(610)  评论(0)  编辑  收藏  举报