JAVA?DOC如何生成標準的JAVA?API文檔詳解

更新時間：2024年06月07日 11:23:07 作者：_BugMan

這篇文章主要給大家介紹了關于JAVA?DOC如何生成標準的JAVA?API文檔的相關資料,Javadoc是Sun公司提供的一種工具,它可以從程序源代碼中抽取類、方法、成員等注釋,然后形成一個和源代碼配套的API幫助文檔,需要的朋友可以參考下

1.什么是JAVA DOC

當我們寫完JAVA代碼，別人要調用我們的代碼的時候要是沒有API文檔是很痛苦的，只能跟進源碼去一個個的看，一個個方法的猜，并且JAVA本來就不是一個重復造輪子的游戲，一般一些常用的輪子早就已經(jīng)早好了，直接拿來用就是。但是拿來用的時候往往由于API文檔的缺失或者不規(guī)范，造成使用上的很多痛苦，大家在很多實際工作中經(jīng)常也會遇到類似的場景：

公司多年累積下來的工具類或者提供底層能力的公共模塊里面積累了很多能力，公司為了代碼規(guī)范也要求我們盡量去調用這些工具類或者公共模塊。但是：

沒有API文檔或者文檔寫的很爛
參數(shù)列表動不動就很長，數(shù)十個甚至幾十個參數(shù)
參數(shù)列表沒有注釋，出現(xiàn)一些莫名其妙的參數(shù)，都不知道怎么傳
方法名也不能見名知意
造成往往要用這些公共能力的時候甚至還要去讀源碼

有讀源碼這個時間，可能自己都重新寫了一個了，而且自己寫的，可能比祖?zhèn)飨聛淼哪切┕ぞ哳愡€更“清爽”一些。于是系統(tǒng)內越來越多工具類堆積，重復造的輪子越來越多，“屎山”越堆越高。

即使有時候我們有API文檔，但是各類API文檔，格式，內容都不相同，沒有統(tǒng)一的規(guī)范，讀起來其實也很慢。所以有沒有一個統(tǒng)一的規(guī)范喃？JAVA官方其實早就想到了這個問題，在JDK1.1發(fā)布的時候就附帶了JAVA DOC，支持用標簽注釋的方式給各個方法做好規(guī)范的說明，然后用JAVA命令一鍵生成可視化的HTML頁面作為API。

2.標簽

標簽是JAVA DOC的核心，用什么標簽，JAVA DOC最后就會對應生成哪些API文檔內容：

@author:

   /**
    * @author John Doe
    */
   public class MyClass {
   }

@version:

/**
    * @version 1.0.1
    */
   public class MyClass {
   }

@param:

/**
    * Concatenates two strings.
    * @param string1 The first string to concatenate.
    * @param string2 The second string to concatenate.
    * @return The concatenated string.
    */
   public String concatenateStrings(String string1, String string2) {
       return string1 + string2;
   }

@return:

/**
    * Returns the sum of two integers.
    * @param num1 The first integer.
    * @param num2 The second integer.
    * @return The sum of num1 and num2.
    */
   public int add(int num1, int num2) {
       return num1 + num2;
   }

@throws 或 @exception: 描述方法可能拋出的異常。

/**
    * Divides two numbers and throws an exception if the divisor is zero.
    * @param dividend The number to be divided.
    * @param divisor The divisor.
    * @return The result of the division.
    * @throws ArithmeticException If the divisor is zero.
    */
   public double safeDivide(double dividend, double divisor) {
       if (divisor == 0) {
           throw new ArithmeticException("Divisor cannot be zero.");
       }
       return dividend / divisor;
   }

@see:

/**
    * See {@link java.util.ArrayList} for more information on dynamic arrays.
    */
   public class MyDynamicArray {
   }

@link: 創(chuàng)建一個鏈接到其他類、方法或字段的鏈接。

/**
    * This method uses the {@link java.util.Collections#shuffle(List)} method to randomize the list.
    */
   public void shuffleList(List<?> list) {
       Collections.shuffle(list);
   }

@since: 指定該元素是從哪個版本開始引入的。

/**
    * A utility class for working with dates.
    * @since 1.5
    */
   public class DateUtils {
   }

@deprecated: 標記不再推薦使用的元素。

/**
    * Old method that should not be used anymore.
    * @deprecated Use the {@link #newMethod()} instead.
    */
   @Deprecated
   public void oldMethod() {
   }

@inheritDoc: 繼承父類或接口的 JavaDoc。

/**
     * {@inheritDoc}
     */
    @Override
    public void someMethod() {
        // Implementation
    }

@parametricType: 用于描述泛型類型參數(shù)。

/**
     * Represents a generic collection.
     * @param <E> The type of elements in this collection.
     */
    public class MyCollection<E> {
    }

@serialField 和 @serialData: 用于序列化類的字段和數(shù)據(jù)。

/**
 * A serializable class.
 * @serialField name The name of the object.
 * @serialData The length of the name.
 */
@Serial
private static final long serialVersionUID = 1L;
?
private String name;
// serialization logic

3.命令

javadoc命令用于生成API文檔，其支持多種參數(shù)：

javadoc [options] [source files]

常用參數(shù)：

-d <directory>: 指定輸出目錄，存放生成的 HTML 文件。
-sourcepath <pathlist>: 指定源文件路徑，可以是多個路徑，用分隔符（如冒號或分號）分隔。
-subpackages <packagename>: 遞歸處理指定包及其子包下的所有類。
-classpath <classpath>: 設置類路徑，用于解析類型引用。
-encoding <encoding>: 指定源文件的字符編碼。
-charset <charset>: 指定生成文檔時使用的字符集。
-windowtitle <text>: 設置文檔窗口標題。
-doctitle <text>: 設置文檔頁面的標題。
-overview <filename>: 指定概述文件，用于文檔的首頁內容。
-exclude <patternlist>: 指定要排除的包或類的模式列表。
-private: 包含私有成員的文檔。
-protected: 默認行為，包含受保護和公開成員的文檔。
-public: 只包含公共成員的文檔。

示例：

假設你有一個名為 com.example 的包，位于 /src/main/java 目錄下，你想生成包含所有公共和受保護成員的 API 文檔，并將輸出文件保存在 /docs/api 目錄下，同時指定字符編碼為 UTF-8，可以使用以下命令：

javadoc -encoding UTF-8 -charset UTF-8 -d /docs/api -sourcepath /src/main/java -subpackages com.example

搞一個類來把注解都用上，然后生成API文檔看看：

package com.eryi.config;

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;

/**
 * @author John Doe
 * @version 1.0.0
 * @since 2022-04-01
 * @deprecated Since version 1.1.0, use the {@link BetterFileManager} instead.
 * This class provides basic file management operations.
 */
@Deprecated
public class FileManager {

    /**
     * @param filePath The path of the file to check.
     * @return True if the file exists, false otherwise.
     * @see File#exists()
     * @throws NullPointerException If the filePath is null.
     */
    public boolean fileExists(String filePath) {
        if (filePath == null) {
            throw new NullPointerException("FilePath cannot be null.");
        }

        File file = new File(filePath);
        return file.exists();
    }

    /**
     * @param fileName The name of the file to create.
     * @param content The content to write into the file.
     * @return The newly created file.
     * @throws IOException If there's any issue creating or writing to the file.
     * @see File#createNewFile()
     * @see FileWriter
     */
    public File createFileWithContent(String fileName, String content) throws IOException {
        File file = new File(fileName);
        if (!file.createNewFile()) {
            throw new IOException("Failed to create file: " + fileName);
        }

        try (FileWriter writer = new FileWriter(file)) {
            writer.write(content);
        }
        return file;
    }

    /**
     * A sample file path constant.
     * @since 1.0.0
     */
    @Deprecated
    public static final String SAMPLE_FILE_PATH = "resources/sample.txt";

    /**
     * @param args Command-line arguments (not used in this example).
     */
    public static void main(String[] args) {
        FileManager fileManager = new FileManager();
        System.out.println("Does sample file exist? " + fileManager.fileExists(SAMPLE_FILE_PATH));
    }
}

直接JAVADOC：