JAVA?DOC如何生成標(biāo)準(zhǔn)的JAVA?API文檔詳解
1.什么是JAVA DOC
當(dāng)我們寫完JAVA代碼,別人要調(diào)用我們的代碼的時候要是沒有API文檔是很痛苦的,只能跟進(jìn)源碼去一個個的看,一個個方法的猜,并且JAVA本來就不是一個重復(fù)造輪子的游戲,一般一些常用的輪子早就已經(jīng)早好了,直接拿來用就是。但是拿來用的時候往往由于API文檔的缺失或者不規(guī)范,造成使用上的很多痛苦,大家在很多實際工作中經(jīng)常也會遇到類似的場景:
公司多年累積下來的工具類或者提供底層能力的公共模塊里面積累了很多能力,公司為了代碼規(guī)范也要求我們盡量去調(diào)用這些工具類或者公共模塊。但是:
沒有API文檔或者文檔寫的很爛
參數(shù)列表動不動就很長,數(shù)十個甚至幾十個參數(shù)
參數(shù)列表沒有注釋,出現(xiàn)一些莫名其妙的參數(shù),都不知道怎么傳
方法名也不能見名知意
造成往往要用這些公共能力的時候甚至還要去讀源碼
有讀源碼這個時間,可能自己都重新寫了一個了,而且自己寫的,可能比祖?zhèn)飨聛淼哪切┕ぞ哳愡€更“清爽”一些。于是系統(tǒng)內(nèi)越來越多工具類堆積,重復(fù)造的輪子越來越多,“屎山”越堆越高。
即使有時候我們有API文檔,但是各類API文檔,格式,內(nèi)容都不相同,沒有統(tǒng)一的規(guī)范,讀起來其實也很慢。所以有沒有一個統(tǒng)一的規(guī)范喃?JAVA官方其實早就想到了這個問題,在JDK1.1發(fā)布的時候就附帶了JAVA DOC,支持用標(biāo)簽注釋的方式給各個方法做好規(guī)范的說明,然后用JAVA命令一鍵生成可視化的HTML頁面作為API。
2.標(biāo)簽
標(biāo)簽是JAVA DOC的核心,用什么標(biāo)簽,JAVA DOC最后就會對應(yīng)生成哪些API文檔內(nèi)容:
@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: 標(biāo)記不再推薦使用的元素。
/** * 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>: 設(shè)置類路徑,用于解析類型引用。
- -encoding <encoding>: 指定源文件的字符編碼。
- -charset <charset>: 指定生成文檔時使用的字符集。
- -windowtitle <text>: 設(shè)置文檔窗口標(biāo)題。
- -doctitle <text>: 設(shè)置文檔頁面的標(biāo)題。
- -overview <filename>: 指定概述文件,用于文檔的首頁內(nèi)容。
- -exclude <patternlist>: 指定要排除的包或類的模式列表。
- -private: 包含私有成員的文檔。
- -protected: 默認(rèn)行為,包含受保護(hù)和公開成員的文檔。
- -public: 只包含公共成員的文檔。
示例:
假設(shè)你有一個名為 com.example 的包,位于 /src/main/java 目錄下,你想生成包含所有公共和受保護(hù)成員的 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:
會在路徑下生成一堆東西,需要用的只有index.html,其它的都是為了支持這個index.html的資源文件而已:
看看效果:
可以看到關(guān)于這個類的什么都有:
總結(jié)
到此這篇關(guān)于JAVA DOC如何生成標(biāo)準(zhǔn)的JAVA API文檔的文章就介紹到這了,更多相關(guān)java doc生成標(biāo)準(zhǔn)JAVA API文檔內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
關(guān)于SaCheckPermission權(quán)限校驗注解
在若依框架(RuoYi)的前后端分離版4.8.x中,SaCheckPermission注解用于權(quán)限校驗,這個注解可以應(yīng)用在方法上,以確保只有具有相應(yīng)權(quán)限的用戶才能訪問該方法2024-11-11SpringSecurity報錯authenticationManager must be 
這篇文章主要介紹了SpringSecurity報錯authenticationManager must be spec的解決方案,具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教2022-11-11java發(fā)送heartbeat心跳包(byte轉(zhuǎn)16進(jìn)制)
這篇文章主要介紹了java發(fā)送heartbeat心跳包(byte轉(zhuǎn)16進(jìn)制),需要的朋友可以參考下2014-05-05