導(dǎo)語：

我們知道javadoc是內(nèi)嵌於JDK中的，因此遵循javadoc規(guī)範(fàn)肯定就是java註解的正統(tǒng)，有了javadoc幫助產(chǎn)生API文檔是非常實(shí)用的。

（學(xué)習(xí)影片分享：java影片教學(xué)）

#1、什麼是註解

註解是為了讓程式碼更具可讀性，降低團(tuán)隊(duì)合作的溝通成本。在一個(gè)團(tuán)隊(duì)中，你的程式碼更清晰、更易讀，更規(guī)範(fàn)，那麼升職加薪肯定是你的，因?yàn)槟憧梢韵嗳蒽陡嗟娜恕?
前陣子聽到一個(gè)說法：你的程式碼寫的只有你一個(gè)人看得懂，那你就是那個(gè)不可或缺的人。說這話的人就是腦殘，寫的程式碼只有自己看的懂得話，大家都不待見，活的像孫子一樣，難道大家都需要孫子嗎？

2、常用註解快速鍵

註解一行：//我是行內(nèi)容
快速鍵：ctrl / 反操作：ctrl /註解一塊：/*我是區(qū)塊內(nèi)容* /
快捷鍵：ctrl shift / 反操作：ctrl shift \javadoc可識(shí)別的註解：

	/**
	 * 我是注釋
	 * 我也是注釋
	 * 我還是注釋，我們都能被javadoc識(shí)別
	 */

3、javadoc規(guī)範(fàn)

遵循javadoc規(guī)範(fàn)，我們就可以使用javadoc指令，產(chǎn)生非常直覺易讀的API文檔，非常方便。
我們?cè)诔淌街谐霈F(xiàn)的註釋可以有意識(shí)地分為兩種，一種是簡易的註釋，給我們自己看的，一種是符合javadoc規(guī)範(fàn)的註釋，目的是產(chǎn)生易讀的文檔。
仔細(xì)閱讀產(chǎn)生的API文檔，有三部分需要我們說明，如圖：

#上面紅框的內(nèi)容都是我添加的註釋，是一個(gè)簡單的Hello類，源碼如下，感興趣可以自己去試試：

/**
  *	@author XXXX
  *	@version 創(chuàng)建時(shí)間：2021年1月21日 下午3:22:01
  *	
  */
public class Hello {

	/**
	 * main()方法簡述(后面這個(gè)dot必不可少).
	 * <p>這就是為了測(cè)試注釋<br>
	 * 沒什么好說明的，只為了說明能出現(xiàn)在這里
	 * @param args 就是系統(tǒng)配的，沒啥說的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}
	
	/**
	 * havaReturn方法就是為了測(cè)試javadoc注釋規(guī)范的.
	 * <p>我發(fā)現(xiàn)只有有返回值的方法才可以使用return標(biāo)簽<br>
	 * 沒有return硬是要用，只會(huì)在javadoc時(shí)候報(bào)錯(cuò)
	 * @param a 輸入的第一個(gè)int類型的參數(shù)
	 * @param b 輸入的第二個(gè)int類型的參數(shù)
	 * @return add 兩個(gè)數(shù)的和運(yùn)算結(jié)果
	 */
	public int haveReturn(int a,int b){
		int add=0;
		add=a+b;
		return add;
	}

}

有幾個(gè)要點(diǎn)需要指出：

要想API文檔出現(xiàn)作者和版本，不僅要在程序註釋中添加@author和@version（需要說明的是，在程序多個(gè)地方註釋@author也只會(huì)在最終文檔中顯示一次，我建議只註一次），還要在編譯的時(shí)候在dos指令中指出：

其中-d folder意思是你把產(chǎn)生的API文檔（其實(shí)是很多網(wǎng)頁組成的）放在folder資料夾中，當(dāng)然folder也可以是個(gè)路徑

方法概要與方法詳細(xì)資料怎麼區(qū)分呢？

/**
	 * main()方法簡述(后面這個(gè)dot必不可少).
	 * <p>這就是為了測(cè)試注釋<br>
	 * 沒什么好說明的，只為了說明能出現(xiàn)在這里
	 * @param args 就是系統(tǒng)配的，沒啥說的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}

你一??定發(fā)現(xiàn)關(guān)於方法的註解都是一大坨，javadoc要如何提取概要呢？沒錯(cuò)，就只靠一個(gè)dot(.)，觀察我註釋裡面提到的那個(gè)dot，那就是提取概要的關(guān)鍵，dot之前是概要，所有的都是詳細(xì)介紹（詳細(xì)介紹是包含概要的）

我們?cè)诔淌街心芸刂谱〉木褪窃]解的排版，但是這種排版並不被javadoc識(shí)別，javadoc發(fā)現(xiàn)一行註釋，只去掉*和空格之後，就一股腦傳過去，注意到生成的文檔是HTML類型的，所以只要在程式中註解HTML語法，就能實(shí)現(xiàn)編輯API文檔格式，不要擔(dān)心太困難，因?yàn)槲覀冎皇怯靡恍┖唵蔚腍TML語法，比如段落

，換行
這些就可以，畢竟註解也不會(huì)很長。

@param 參數(shù)1 說明（注意格式）

有回傳值就寫，沒回傳值就不用寫，寫了反而會(huì)報(bào)錯(cuò)

其實(shí)寫類別註解、方法註解非常簡單，只要在類別、方法前敲擊/**，再按回車，系統(tǒng)就會(huì)自動(dòng)添加，並且系統(tǒng)如何添加也是我們可以修改的

如何修改新檔案時(shí)出現(xiàn)的內(nèi)容，如何讓自動(dòng)補(bǔ)全的註解受我們控制（待辦）

我們從標(biāo)準(zhǔn)類別檔案中看到這個(gè)：

#我們都知道，out是System類別的屬性（欄位），它是PrintStream類型的，類別PrintStream中定義了很多方法，這些自然也是out的方法，因此在定義out的時(shí)候，它前面的註釋中就有很多@see,這就是使用@see註釋最好的地方，我們推薦在定義類別的字段時(shí)，如果字段是複合類型的（特別是自定義的複合類型），那麼就在前面註釋@see,這樣有兩方面的好處，請(qǐng)看圖：

相信這兩張圖你都不陌生，第一個(gè)是寫程式時(shí)候遊標(biāo)停留可以出現(xiàn)的提示，如果你按照javadoc規(guī)格來寫註釋，那麼你自己寫的程式也會(huì)出現(xiàn)這些極有幫助的提示。第二個(gè)是java8 API文件關(guān)於String類別裡的out欄位的詳細(xì)描述，這也是@see的功勞，你寫了@see，你自己的專案API文件中也有這樣的註解。

相關(guān)推薦：java入門教學(xué)

以上是javadoc規(guī)格介紹的詳細(xì)內(nèi)容。更多資訊請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！