一、什麼是JavaDoc

1. JavaDoc，從程式原始碼中抽取類、方法、成員等註釋形成一個和原始碼程式碼配套的API幫助文件。

2. JavaDoc命令是用來生成自己API文件的。

3. 通俗來講，只要你在java原始碼中按一定格式寫註釋，就可以利用javadoc這款工具自動生成配套的API文件。

二、JavaDoc註釋分類

1. JavaDoc註釋根據寫法和位置不同。主要分為：

   • 寫在類/方法上面的javadoc註釋。寫在類和方法上面的javadoc註釋位置不同，但寫法相同。

     • 用於描述該類或方法的作用；

     • 此種註釋按順序分為概要描述、詳細描述、文件標記三段；

     • 概要描述：

       • 簡要描述作用，以英文句號結束，這局話會被提取並放到索引目錄中；

       • 當識別到第一個英文句號時，會自動認為概要描述已經結束，緊跟以後的話不會被放到概要描述中；為避免這種情況，可以在英文句號後加上&nbsp，系統會判斷&nbsp後的下一個英文句號為概要描述結束的標誌。

     • 詳細描述

       • 詳細描述作用，每段話都以英文句號結束

       • 詳細描述中可以使用html標籤，如<P>,<a>,<li>等。

     • 文件標記，類似於小標籤一樣的宣告。描述部分和文件標記之間必須空一行。

   • 寫在欄位上面的javadoc註釋

     • 只有public的欄位才需要註釋，通常是static的。

       /**
       *the static field a
       */
       publicstatic int a = 1；
        
       

   • 寫在包上面的javadoc註釋

     • 格式和寫在類/方法上面的javadoc註釋一樣。

     • 介紹這個包是幹嘛的，包的結構，在使用方面的注意事項等資訊。

     • 包註釋是寫在package-info.java檔案中的，這個檔案在建立包時會自動順帶生成。

2. 注意事項

   • 所有的javadoc註釋都以/**開頭，*/結尾。

   • 每種javadoc註釋都要和其後面對應的類/方法/欄位/包 保持同樣的縮排

     //錯誤javadoc註釋
     class Student{
     /**
     *沒有和下面的方法保持同樣的縮排，是錯誤的寫法。
     */
         public int add(int num1,int num2){
             ...
         }
     }
      
     

三、如何生產JavaDoc文件

1. 使用dos命令視窗生成

   • 在dos命令視窗（win+R，輸入cmd），在目標檔案所在目錄輸入javadoc+（-encoding UTF-8 -charset UTF-8）檔名.java

   • -encoding UTF-8 -charset UTF-8是為了讓中文更好的顯示。

2. 使用IDEA生產javadoc文件

   • 1.【Tools→Generate JavaDoc】

   • 2.按照紅色標號即可生產javadoc文件

     • Generate JAVaDoc Scope:選擇要生成javaDoc文件的檔案：整個專案、當前java檔案、自選

     • Output directory：java文件生成路徑，建議新建一個資料夾用於儲存javadoc文件。路徑要是用英文路徑

     • Locale：文件的提示資訊 建議填zh_CN ;zh_CN 代表中文

     • Other command line arguments：編碼、title等傳遞給javadoc的引數。一般這樣寫：-encoding UTF-8 -charset UTF-8 -windowtitle “文件HTML頁面標籤的標題” -link http://docs.Oracle.com/javase/7/docs/api

     • 橙色框中代表對哪些生成文件，預設是隻對public和protected生成文件。將其向上或向下滑動可改變

     • 其餘的就先不瞭解。

   • 3.結果

     • 找到生成的html

   • 也可以直接開啟index.html