javadoc規格介紹

王林轉載: 2021-01-25 09:49:392668瀏覽

javadoc規格介紹

導語：

我們知道javadoc是內嵌於JDK中的，因此遵循javadoc規範肯定就是java註解的正統，有了javadoc幫助產生API文檔是非常實用的。

（學習影片分享：java影片教學）

#1、什麼是註解

註解是為了讓程式碼更具可讀性，降低團隊合作的溝通成本。在一個團隊中，你的程式碼更清晰、更易讀，更規範，那麼升職加薪肯定是你的，因為你可以相容於更多的人。
前陣子聽到一個說法：你的程式碼寫的只有你一個人看得懂，那你就是那個不可或缺的人。說這話的人就是腦殘，寫的程式碼只有自己看的懂得話，大家都不待見，活的像孫子一樣，難道大家都需要孫子嗎？

2、常用註解快速鍵

註解一行：//我是行內容
快速鍵：ctrl / 反操作：ctrl /註解一塊：/*我是區塊內容* /
快捷鍵：ctrl shift / 反操作：ctrl shift \javadoc可識別的註解：

	/**
	 * 我是注释
	 * 我也是注释
	 * 我还是注释，我们都能被javadoc识别
	 */

3、javadoc規範

遵循javadoc規範，我們就可以使用javadoc指令，產生非常直覺易讀的API文檔，非常方便。
我們在程式中出現的註釋可以有意識地分為兩種，一種是簡易的註釋，給我們自己看的，一種是符合javadoc規範的註釋，目的是產生易讀的文檔。
仔細閱讀產生的API文檔，有三部分需要我們說明，如圖：

javadoc規格介紹

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

/**
  *	@author XXXX
  *	@version 创建时间：2021年1月21日 下午3:22:01
  *	
  */
public class Hello {

	/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}
	
	/**
	 * havaReturn方法就是为了测试javadoc注释规范的.
	 * <p>我发现只有有返回值的方法才可以使用return标签<br>
	 * 没有return硬是要用，只会在javadoc时候报错
	 * @param a 输入的第一个int类型的参数
	 * @param b 输入的第二个int类型的参数
	 * @return add 两个数的和运算结果
	 */
	public int haveReturn(int a,int b){
		int add=0;
		add=a+b;
		return add;
	}

}

有幾個要點需要指出：

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

javadoc -d folder -version -author Hello.java

其中-d folder意思是你把產生的API文檔（其實是很多網頁組成的）放在folder資料夾中，當然folder也可以是個路徑

方法概要與方法詳細資料怎麼區分呢？

/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}

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

如何控制產生的文件中的註解排版

我們在程式中能控制住的就是註解的排版，但是這種排版並不被javadoc識別，javadoc發現一行註釋，只去掉*和空格之後，就一股腦傳過去，注意到生成的文檔是HTML類型的，所以只要在程式中註解HTML語法，就能實現編輯API文檔格式，不要擔心太困難，因為我們只是用一些簡單的HTML語法，比如段落

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

@param 參數1 說明（注意格式）

@return 回傳值說明（注意格式）

有回傳值就寫，沒回傳值就不用寫，寫了反而會報錯

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

如何修改新檔案時出現的內容，如何讓自動補全的註解受我們控制（待辦）

我們從標準類別檔案中看到這個： javadoc規格介紹

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

#######

javadoc規格介紹

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

javadoc規格介紹

相關文章