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
  {@docRoot}	指明當前文檔根目錄的路徑	Directory Path
  @exception	標志一個類拋出的異常	@exception exception-name explanation
  {@inheritDoc}	從直接父類繼承的注釋	Inherits a comment from the immediate surperclass.
  {@link}	插入一個到另一個主題的鏈接	{@link name text}
  {@linkplain}	插入一個到另一個主題的鏈接，但是該鏈接顯示純文本字體	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.
  {@value}	顯示常量的值，該常量必須是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 }用於連接到方法時 ：包名.類名#方法名(參數類型)，方法名前必須是 # 號，用法 ： {@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

      • java.lang.Object
      • • 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)
          

          已過時。 已過期

          返回輸入信息

          • 參數:

            input - 輸入的信息

          • 返回:

            String

          • 另請參閱:

            字符串

        • 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 - 不支持算法