JAVA?DOC如何生成標(biāo)準(zhǔn)的JAVA?API文檔詳解
1.什么是JAVA DOC
當(dāng)我們寫完JAVA代碼,別人要調(diào)用我們的代碼的時(shí)候要是沒(méi)有API文檔是很痛苦的,只能跟進(jìn)源碼去一個(gè)個(gè)的看,一個(gè)個(gè)方法的猜,并且JAVA本來(lái)就不是一個(gè)重復(fù)造輪子的游戲,一般一些常用的輪子早就已經(jīng)早好了,直接拿來(lái)用就是。但是拿來(lái)用的時(shí)候往往由于API文檔的缺失或者不規(guī)范,造成使用上的很多痛苦,大家在很多實(shí)際工作中經(jīng)常也會(huì)遇到類似的場(chǎng)景:
公司多年累積下來(lái)的工具類或者提供底層能力的公共模塊里面積累了很多能力,公司為了代碼規(guī)范也要求我們盡量去調(diào)用這些工具類或者公共模塊。但是:
沒(méi)有API文檔或者文檔寫的很爛
參數(shù)列表動(dòng)不動(dòng)就很長(zhǎng),數(shù)十個(gè)甚至幾十個(gè)參數(shù)
參數(shù)列表沒(méi)有注釋,出現(xiàn)一些莫名其妙的參數(shù),都不知道怎么傳
方法名也不能見(jiàn)名知意
造成往往要用這些公共能力的時(shí)候甚至還要去讀源碼
有讀源碼這個(gè)時(shí)間,可能自己都重新寫了一個(gè)了,而且自己寫的,可能比祖?zhèn)飨聛?lái)的那些工具類還更“清爽”一些。于是系統(tǒng)內(nèi)越來(lái)越多工具類堆積,重復(fù)造的輪子越來(lái)越多,“屎山”越堆越高。
即使有時(shí)候我們有API文檔,但是各類API文檔,格式,內(nèi)容都不相同,沒(méi)有統(tǒng)一的規(guī)范,讀起來(lái)其實(shí)也很慢。所以有沒(méi)有一個(gè)統(tǒng)一的規(guī)范喃?JAVA官方其實(shí)早就想到了這個(gè)問(wèn)題,在JDK1.1發(fā)布的時(shí)候就附帶了JAVA DOC,支持用標(biāo)簽注釋的方式給各個(gè)方法做好規(guī)范的說(shuō)明,然后用JAVA命令一鍵生成可視化的HTML頁(yè)面作為API。
2.標(biāo)簽
標(biāo)簽是JAVA DOC的核心,用什么標(biāo)簽,JAVA DOC最后就會(huì)對(duì)應(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)建一個(gè)鏈接到其他類、方法或字段的鏈接。
/** * This method uses the {@link java.util.Collections#shuffle(List)} method to randomize the list. */ public void shuffleList(List<?> list) { Collections.shuffle(list); }
@since: 指定該元素是從哪個(gè)版本開始引入的。
/** * 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>: 指定源文件路徑,可以是多個(gè)路徑,用分隔符(如冒號(hào)或分號(hào))分隔。
- -subpackages <packagename>: 遞歸處理指定包及其子包下的所有類。
- -classpath <classpath>: 設(shè)置類路徑,用于解析類型引用。
- -encoding <encoding>: 指定源文件的字符編碼。
- -charset <charset>: 指定生成文檔時(shí)使用的字符集。
- -windowtitle <text>: 設(shè)置文檔窗口標(biāo)題。
- -doctitle <text>: 設(shè)置文檔頁(yè)面的標(biāo)題。
- -overview <filename>: 指定概述文件,用于文檔的首頁(yè)內(nèi)容。
- -exclude <patternlist>: 指定要排除的包或類的模式列表。
- -private: 包含私有成員的文檔。
- -protected: 默認(rèn)行為,包含受保護(hù)和公開成員的文檔。
- -public: 只包含公共成員的文檔。
示例:
假設(shè)你有一個(gè)名為 com.example 的包,位于 /src/main/java 目錄下,你想生成包含所有公共和受保護(hù)成員的 API 文檔,并將輸出文件保存在 /docs/api 目錄下,同時(shí)指定字符編碼為 UTF-8,可以使用以下命令:
javadoc -encoding UTF-8 -charset UTF-8 -d /docs/api -sourcepath /src/main/java -subpackages com.example
搞一個(gè)類來(lái)把注解都用上,然后生成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:
會(huì)在路徑下生成一堆東西,需要用的只有index.html,其它的都是為了支持這個(gè)index.html的資源文件而已:
看看效果:
可以看到關(guān)于這個(gè)類的什么都有:
總結(jié)
到此這篇關(guān)于JAVA DOC如何生成標(biāo)準(zhǔn)的JAVA API文檔的文章就介紹到這了,更多相關(guān)java doc生成標(biāo)準(zhǔn)JAVA API文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
- 在Java中,生成隨機(jī)數(shù)有兩種方法。1是使用Random類。2是使用Math類中的random方法??聪旅娴睦邮褂冒?/div> 2013-11-11
JavaFX Application應(yīng)用實(shí)例
下面小編就為大家?guī)?lái)一篇JavaFX Application應(yīng)用實(shí)例。小編覺(jué)得挺不錯(cuò)的,現(xiàn)在就分享給大家,也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2016-10-10SpringMVC如何接收參數(shù)各種場(chǎng)景
這篇文章主要介紹了SpringMVC如何接收參數(shù)各種場(chǎng)景,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2021-11-11Springboot 接口對(duì)接文件及對(duì)象的操作方法
這篇文章主要介紹了Springboot 接口對(duì)接文件及對(duì)象的操作,本文通過(guò)實(shí)例代碼給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下2023-07-07關(guān)于SaCheckPermission權(quán)限校驗(yàn)注解
在若依框架(RuoYi)的前后端分離版4.8.x中,SaCheckPermission注解用于權(quán)限校驗(yàn),這個(gè)注解可以應(yīng)用在方法上,以確保只有具有相應(yīng)權(quán)限的用戶才能訪問(wèn)該方法2024-11-11SpringSecurity報(bào)錯(cuò)authenticationManager must be 
這篇文章主要介紹了SpringSecurity報(bào)錯(cuò)authenticationManager must be spec的解決方案,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2022-11-11Springboot 如何設(shè)置啟動(dòng)內(nèi)存
這篇文章主要介紹了Springboot 如何設(shè)置啟動(dòng)內(nèi)存,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2022-02-02java發(fā)送heartbeat心跳包(byte轉(zhuǎn)16進(jìn)制)
這篇文章主要介紹了java發(fā)送heartbeat心跳包(byte轉(zhuǎn)16進(jìn)制),需要的朋友可以參考下2014-05-05最新評(píng)論