java文檔註釋規範（一）

時間 2020-08-22

標籤 java 文檔註釋規範欄目 Java 简体版

原文原文鏈接

https://blog.csdn.net/huangsiqian/article/details/82725214html

Javadoc工具將從四種不一樣類型的「源」文件生成輸出文檔：Java語言類的源文件（.java），包註釋文件，概述註釋文件和其餘未處理的文件。java

包註釋文件（Package Comment File）
每一個包都有本身的文檔註釋。有兩種方式來建立包註釋文件：算法

package-info.java - 能夠包含包的聲明，包註解（anotation），包註釋和Javadoc 標籤（tag）。包註釋放在包聲明以前。這是JDK 5.0新引入的特性。以下。api

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 將被忽略。以下。app

File: java/applet/package.htmlide

 
<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註釋，則遞歸地將整個算法應用於超類。

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。