首頁  >  文章  >  Java  >  javadoc規格介紹

javadoc規格介紹

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

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規格介紹

javadoc規格介紹

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文件中也有這樣的註解。

相關推薦:java入門教學

以上是javadoc規格介紹的詳細內容。更多資訊請關注PHP中文網其他相關文章!

陳述:
本文轉載於:csdn.net。如有侵權,請聯絡admin@php.cn刪除