https://blog.csdn.net/huangsiqian/article/details/82725214
Javadoc工具將從四種不同類型的“源”文件生成輸出文檔：Java語言類的源文件（.java），包注釋文件，概述注釋文件和其他未處理的文件。
包注釋文件（Package Comment File）
每個包都有自己的文檔注釋。有兩種方式來創建包注釋文件：
package-info.java - 可以包含包的聲明，包注解（anotation），包注釋和Javadoc 標簽（tag）。包注釋放在包聲明之前。這是JDK 5.0新引入的特性。如下。
File: java/applet/package-info.java 注意：文檔注釋塊內部行首的*號是可選的
/** * Provides the classes necessary to create an applet and the classes an applet uses * to communicate with its applet context. * <p> * The applet framework involves two entities: * the applet and the applet context. An applet is an embeddable window (see the * {@link java.awt.Panel} class) with a few extra methods that the applet context * can use to initialize, start, and stop the applet. * * @since 1.0 * @see java.awt */ package java.lang.applet;
package.html - 只能包含包注釋和Javadoc標簽，不能包含包注解。注釋包含在<body>元素內部。
注意：只能包含其中一個文件，如果同時包含兩個文件，則 package.html 將被忽略。如下。
File: java/applet/package.html
<HTML> <BODY> Provides the classes necessary to create an applet and the classes an applet uses to communicate with its applet context. <p> The applet framework involves two entities: the applet and the applet context. An applet is an embeddable window (see the {@link java.awt.Panel} class) with a few extra methods that the applet context can use to initialize, start, and stop the applet. @since 1.0 @see java.awt </BODY> </HTML>
包注釋的第一句應該對包進行概括。Javadoc tool 將會將這句話作為summary statement.對於包注釋內容的具體書寫可以參考：How to Write Doc Comments for Javadoc
javadoc工具將會以如下方式處理包注釋文件：
復制注釋並進行處理（對於package.html，復制<body>和</ body> HTML標記之間的所有內容）。
處理注釋中存在的包標簽。
將處理后的文本插入生成的包摘要頁面的底部，參見java api 文檔格式。
將包注釋的第一句復制到包摘要頁面的頂部。 並將包名稱和第一個句子添加到概述頁面上的包列表中。
概述注釋文件（Overview Comment File）
Javadoc工具將由它生成概述頁面。可以將概述注釋文件命名為任何名稱（一般命名為overview.html）並放在任何位置（通常放在source tree的頂層）。例如，如果java.applet包的源文件包含在C：\ user \ src \ java \ applet目錄中，則可以將概述注釋文件創建為C：\ user \ src \ overview.html。
概述注釋文件的內容也是HTML編寫的大文件注釋，類似於包注釋文件。注釋的第一個句子作為應用程序或包集合的摘要，不要在<body>和第一個句子之間放置標題或任何其他文本。除了內嵌標簽（例如{@link}）之外的所有標簽必須出現在主要描述之后。如果應用@see標簽，則必須用fully-qualified name。
運行Javadoc工具時，使用-overview選項指定概述注釋文件名。javadoc工具處理該文件的方式類似於包注釋文件的處理。
復制<body>和</ body>標記之間的所有內容並進行處理。
處理注釋中存在的概述標簽。
將處理后的文本插入生成的概述頁面的底部。
將概述注釋的第一句復制到概述摘要頁面的頂部。
其他未處理的文件（Miscellaneous Unprocessed Files）
可以在源文件中包含任何雜項文件（由Javadoc工具復制到目標目錄）。通常包括圖像文件，Java示例源代碼（.java）和類（.class）文件，獨立的HTML文件。
未處理的文件應放在包含源文件的任何包目錄下，名為doc-files的目錄中。可以包括圖像，示例代碼，源文件，.class文件，applet和HTML文件。例如，如果要在java.awt.Button類文檔中包含按鈕button.gif的圖像，則將該文件放在/ home / user / src / java / awt / doc-files /目錄中。請注意，doc-files目錄不應位於/ home / user / src / java / doc-files中，因為java目錄不直接包含任何源文件。
這些未處理文件的所有鏈接都必須是硬編碼的，因為Javadoc工具只是將目錄及其所有內容復制到目標。例如，Button.java doc注釋中的鏈接可能如下所示
/** *此按鈕如下所示： * <img src =“doc-files / Button.gif”> */
測試文件和模板文件
一些開發人員表示他們希望將源代碼樹中的測試文件和模板文件存儲在相應的源文件附近。也就是說，他們希望將它們放在這些源文件的同一目錄或子目錄中。
如果通過顯式傳入單個源文件名來運行Javadoc工具，則可以故意忽略測試和模板文件以防止它們被處理。但是，如果要傳遞包名稱或通配符來運行Javadoc工具，則需要遵循某些規則以確保不處理這些測試文件和模板文件。
測試文件與模板文件的不同之處在於前者是合法的，可編譯的源文件，而后者不是，但可能以“.java”結尾。
可以將測試文件放在子目錄中（該子目錄是一個無效的包名）。例如，如果要在com.package1中為源文件添加測試文件：
com/package1/test-files/
Javadoc工具將跳過測試目錄，沒有任何警告。
如果您的測試文件包含doc注釋，則可以設置單獨的Javadoc工具運行，以通過傳入帶有通配符的測試源文件名來生成測試文件的文檔，例如com / package1 / test-files / * .java。
源文件的模板文件的名稱通常以“.java”結尾，並且不可編譯。如果您有要保留在源目錄中的源文件的模板，則可以使用短划線（例如Buffer-Template.java）或任何其他非法Java字符命名，以防止對其進行處理。
Java源文件中的文檔注釋
注釋的位置：文檔注釋僅緊接放置在類，接口，構造函數，方法或字段聲明之前。放置在方法體中的文檔注釋將被忽略。
文檔注釋由主要描述部分 + 標簽部分組成：主要描述在起始分隔符/ **之后開始，一直到標簽部分。 標簽部分以第一個塊標簽開始，塊標記由一個@字符定義（忽略前導 *，空格和前導分隔符/ **）。 可以只有標簽部分而沒有主要描述部分。 標簽部分開始后，不能續接主要描述部分。 標簽的參數可以跨越多行。 可以有任意數量的標簽：某些類型的標簽可以重復，而其他標簽則不能重復。 例如，這個@see標簽部分
/** * This sentence would hold the main description for this doc comment. * @see java.lang.Object */
塊標簽和內嵌標簽。
有兩種標簽：塊標簽（顯示為@tag（也稱為“獨立標簽”））和內嵌標簽（顯示在花括號內）為{@tag}。塊標簽必須出現在行的開頭，忽略前導 *，空格和分隔符（/ **）。 這意味着可以在文本的其他位置使用@字符，而不會被解釋為標簽的開始。 如果要以@字符作為一行的開始（非標簽的開始），請使用HTML實體 @。 每個塊標簽都有關聯的文本，包括標簽之后的任何文本，直到下一個標簽或文檔注釋的結尾。關聯文本可以跨越多行。在允許文本的任何地方允許放置內嵌標簽。 以下示例包含塊標簽@deprecated和內嵌標簽{@link}。
/** * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */
注釋以HTML格式編寫：文本必須用HTML編寫，應該使用HTML實體並且可以使用HTML標簽。 例如，小於（<）和大於（>）符號應該寫為＆lt; 和＆gt;。 同樣，＆符號應該寫成＆amp; 以下示例中顯示了粗體HTML標記<b>。
/** * This is a <b>doc</b> comment. * @see java.lang.Object
前導 * ：每行上的前導星號（*）字符是可選的。從1.4開始，如果省略行上的前導星號，則不再刪除前導空格。這使您可以將代碼示例直接粘貼到<PRE>標記內，並且可以遵循其縮進。瀏覽器通常更加統一地解釋空格。注意，縮進是相對於左邊距（而不是分隔符/ **或<PRE>標記）。
每個文檔注釋的第一句應該是一個簡短的句子，包含對已聲明實體的簡明但完整的描述。這句話在第一個句點處結（后面緊跟空格，制表符或行終止符），或者在第一個塊標簽前結束。 Javadoc工具將第一個句子復制到HTML頁面頂部的成員摘要中。
Java允許在單個語句中聲明多個字段，但此語句只能有一個文檔注釋。因此，如果您需要為每個字段添加單獨的文檔注釋，則必須分別聲明每個字段。例如，以下文檔注釋沒有意義，應當作為兩個字段聲明處理：
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this
在為成員（members）編寫文檔注釋時，最好不要使用HTML標題標簽，例如<H1>和<H2>。因為Javadoc工具會創建整個結構化的文檔，而這些標題標簽可能會影響對生成文件的格式化 。不過，可以在類和包注釋中使用這些標題標簽。
自動復制方法注釋
Javadoc工具能夠在以下兩種情況下復制或“繼承”類和接口中的方法注釋。注意：構造函數，字段和嵌套類不繼承文檔注釋。
當方法注釋中缺少一個主要描述或@return，@ param或@throws標簽時，Javadoc工具從其所重寫或實現的方法中復制相應的主要描述或標簽注釋（如果有的話）。（復制算法見下述：用於繼承方法注釋的算法）
更具體地說，當缺少某個特定參數的@param標簽時，將從繼承層次結構中的方法復制該參數的注釋。如果缺少某個特定異常的@throws標簽，則僅在該異常已被聲明時才復制@throws標簽。此行為與1.3版本及更早版本形成相違背（其中，任何主要描述或標簽的存在將阻止所有注釋被繼承）。
顯式繼承-在方法主要描述或@return，@ param或@throws標簽注釋中插入內聯標記{@inheritDoc} ， 相應的主要描述或標簽注釋將復制到該方法。被繼承的方法所在的源文件只需要在-sourcepath指定的路徑上，以便文檔注釋可用於實際的復制。無論是類還是其包都不需要在命令行中傳入。這與1.3.x及更早版本形成相違背（其中類必須是被文檔記錄的類（documented class））。
從類和接口繼承注釋有三種可能情況：
當類中的方法重寫超類中的方法時
當接口中的方法覆蓋超級接口中的方法時
當類中的方法實現接口中的方法時
在前兩種情況下，對於方法覆蓋，Javadoc工具在重寫的方法的文檔中生成一個子標題“Overrides”，其中包含指向它所覆蓋的方法的鏈接，無論注釋是否被繼承。
在第三種情況下，Javadoc工具在重寫方法的文檔中生成子標題“Specified by”，並帶有指向它所實現的方法的鏈接。無論注釋是否被繼承。
用於繼承方法注釋的算法 - 如果方法沒有文檔注釋或者方法的文檔注釋中有{@inheritDoc}標簽，則Javadoc工具使用以下算法搜索最具體適用的注釋，該算法優先考慮接口，而不是超類：
按照它們在方法聲明中的implements（或extends）后面出現的順序查看每個直接實現（或擴展）的接口。使用此方法找到的第一個doc注釋。
如果步驟1未能找到文檔注釋，則以與步驟1中檢查的順序相同的順序遞歸地將此整個算法應用於每個直接實現（或擴展）的接口。
如果步驟2找不到文檔注釋，並且這是一個除Object之外的類（不是接口）：1，如果超類具有此方法的doc注釋，那么就使用它。2，如果步驟1未能找到doc注釋，則遞歸地將整個算法應用於超類。