javadoc規范是什么

小編給大家分享一下javadoc規范是什么，相信大部分人都還不怎么了解，因此分享這篇文章給大家參考一下，希望大家閱讀完這篇文章后大有收獲，下面讓我們一起去了解一下吧！

導語：

我們知道javadoc是內嵌于JDK中的，因此遵循javadoc規范肯定就是java注釋的正統，有了javadoc幫助生成API文檔是非常實用的。

1、什么是注釋

注釋是為了使代碼更具有可讀性，降低團隊合作的交流成本。在一個團隊中，你的代碼更清晰、更易讀，更規范，那么升職加薪肯定是你的，因為你可以兼容更多的人。
前段時間聽到一個說法：你的代碼寫的只有你一個人看得懂，那你就是那個不可或缺的人。說這話的人就是腦殘，寫的代碼只有自己看的懂得話，大家都不待見，活的像孫子一樣，難道大家都需要孫子嗎？

2、常用注釋快捷鍵

注釋一行：//我是行內容
快捷鍵：ctrl+/ 反操作：ctrl+/注釋一塊：/*我是塊內容*/
快捷鍵：ctrl+shift+/ 反操作：ctrl+shift+\javadoc可識別的注釋：

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

3、javadoc規范

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

上面紅框的內容都是我添加的注釋，是一個簡單的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語法，比如段落<p>，換行<br>這些就可以，畢竟注釋也不會很長。

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

@return 返回值 說明（注意格式）
有返回值就寫，沒返回值就不用寫，寫了反而會報錯

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

如何修改新建文件時出現的內容，如何使自動補全的注釋受我們控制（待辦）

我們從標準類文件中看到這個：

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

相信這兩張圖你都不陌生，第一個是寫程序時候光標停留可以出現的提示，如果你按照javadoc規范來寫注釋，那么你自己寫的程序也會出現這些極有幫助的提示。第二個是java8 API文檔關于String類里的out字段的詳細描述，這也是@see的功勞，你寫了@see，你自己的項目API文檔中也有這樣的注釋。

以上是“javadoc規范是什么”這篇文章的所有內容，感謝各位的閱讀！相信大家都有了一定的了解，希望分享的內容對大家有所幫助，如果還想學習更多知識，歡迎關注億速云行業資訊頻道！