JAVA如何用javadoc生成標(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è)版本開(kāi)始引入的。
/**
* 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ù)和公開(kāi)成員的文檔。
- -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如何用javadoc生成標(biāo)準(zhǔn)的JAVA API文檔的文章就介紹到這了,更多相關(guān)javadoc生成JAVA API文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
解決@NonNull @org.jetbrains.annotations.NotNull報(bào)紅的問(wèn)題
這篇文章主要介紹了解決@NonNull @org.jetbrains.annotations.NotNull報(bào)紅的問(wèn)題,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2023-01-01
java 中模擬UDP傳輸?shù)陌l(fā)送端和接收端實(shí)例詳解
這篇文章主要介紹了java 中模擬UDP傳輸?shù)陌l(fā)送端和接收端實(shí)例詳解的相關(guān)資料,需要的朋友可以參考下2017-03-03
舉例講解Java設(shè)計(jì)模式編程中Decorator裝飾者模式的運(yùn)用
這篇文章主要介紹了Java設(shè)計(jì)模式編程中Decorator裝飾者模式的運(yùn)用,裝飾者模式就是給一個(gè)對(duì)象動(dòng)態(tài)的添加新的功能,裝飾者和被裝飾者實(shí)現(xiàn)同一個(gè)接口,裝飾者持有被裝飾者的實(shí)例,需要的朋友可以參考下2016-05-05
struts1登錄示例代碼_動(dòng)力節(jié)點(diǎn)Java學(xué)院整理
這篇文章主要介紹了struts1登錄示例代碼,需要的朋友可以參考下2017-08-08
springboot3整合knife4j詳細(xì)圖文教程(swagger增強(qiáng))
開(kāi)發(fā)api提供對(duì)應(yīng)的接口規(guī)范進(jìn)行聯(lián)調(diào)或并行開(kāi)發(fā),api文檔管理必不可少,常用的Knife4j基于swagger(依賴已經(jīng)compile),可以進(jìn)行管理,下面這篇文章主要給大家介紹了關(guān)于springboot3整合knife4j的相關(guān)資料,需要的朋友可以參考下2024-03-03
SpringBoot優(yōu)雅捕捉異常的兩種方法小結(jié)
SpringBoot框架對(duì)異常的處理提供了幾種很強(qiáng)大的方法,我們可以通過(guò)@ControllerAdvice和@ExceptionHandler注解實(shí)現(xiàn)全局異常的處理,下面就來(lái)介紹一下這兩種方法的實(shí)現(xiàn),感興趣的可以了解一下2024-08-08
Java實(shí)現(xiàn)的對(duì)稱加密算法AES定義與用法詳解
這篇文章主要介紹了Java實(shí)現(xiàn)的對(duì)稱加密算法AES,結(jié)合實(shí)例形式分析了對(duì)稱加密算法AES的定義、特點(diǎn)、用法及使用場(chǎng)景,需要的朋友可以參考下2018-04-04
解決springboot報(bào)錯(cuò)找不到自動(dòng)注入的service問(wèn)題
這篇文章主要介紹了解決springboot報(bào)錯(cuò)找不到自動(dòng)注入的service問(wèn)題,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2021-08-08

