java基礎學習（四）：註釋和javadoc使用

  Java語言是一門強類型語言。強類型包含兩方面的含義：（1）所有的變量必須先聲明、後使用。 （2）指定類型的變量只能接受類型與之匹配的值。強類型語言可以在編譯過程中發現源代碼的錯誤，從而保證程序更加健壯。

4.1 註釋

！！！ 記住，一定要多寫註釋

4.1.1 單行註釋

public class Commentest
{
	//單行註釋
	public static void main(string[] args)
	{
		//單行註釋輸出
		System.out.println("Hello World");
	}
}

4.1.2 多行註釋

public class Commentest
{
	/*
	多行註釋
	哈哈哈
	*/
	public static void main(string[] args)
	{
		System.out.println("Hello World");
	}
}

  註釋不僅可以給人思路，還可以debug，把語句註釋，運行看看是不是這個語句所產生的錯誤。

4.1.3 Java 9 增強文檔註釋

  相信單行註釋，多行註釋大家聽過了。但Java還有這一種更加牛逼額的註釋：文檔註釋。如果編寫Java源代碼時添加了合適的文檔註釋，然後JDK提供的javadoc工具可以直接將源代碼裏的文檔註釋提取成一份系統的API文檔。
  API文檔是啥?其實就是在你開發一個大型號的軟件的時候，要定義幾千幾萬各類，這時候是不是需要一份說明文檔，用於說明每個類、每個方法的用途。當其他人使用一個類或一個方法時，他無須關心這個類或方法的具體實現，他只要知道這個類或方法的功能即可，然後使用這個這個類或方法來實現具體目的，也就是通過調用應用程序接口(API)來編程。API文檔就是用以說明這些應用程序接口的文檔。
  大家可以到Java的官方網站去下載API文檔。這裏我就不寫了，網上博客特別多。下載好後點打開/docs/api 路徑下，打開index.html 即可。長相大概如下圖所示。

  好像已經到了Java14去了，太快了，具體api文檔的內容我也不是特別瞭解，等我以後稍微瞭解之後再來寫一寫。
  同樣，在開發中定義類、方法時也可以添加文檔註釋，然後使用javadoc工具來生成自己API文檔。
  問題來了，API文檔重不重要？
  毫無疑問，API是Java提供的基本編程接口，當使用Java語言進行編程時，不可能把所有的Java類、所有方法都記下來，當編程遇到不會的地方，就可以查找。所以，查看API文檔的方法是學習Java的一個最基本的技能。
  文檔註釋以斜線後緊跟兩個星號(/**)開始，以星號後緊跟一個斜線(*/)結束，中間部分全部都是文檔註釋，會被提到API文檔中。
  例如，下面先編寫一個JavadocTest類，這個類裏包含了對類、方法、成員變量的文檔註釋。

  下面我們來嘗試一下：

(一):編寫一個 JavadocTest.java類：

package lee;
/**
 * Description:
 * 網站：<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java語言概述與開發</a><br>
 * Copyright (C), 2020, Li Weile<br>
 * This program is testing the funtion of javadoc. <br>
 * Program Name: test_javadoc <br>
 * Date: 2020-04-25 <br>
 * @author LiWeile [email protected]
 * @version 1.0
 */
public class JavadocTest
{
	/**
	 * 簡單測試成員變量
	 */
	protected String name;
	
	/**
	 * 主方法：程序的入口
	 */
	public static void main(String[] args)
	{
		System.out.println("Hello World!");
	}
}

（二）：編寫一個 Test.java

package yeeku;
/**
 * Description:
 * 網站：<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java語言概述與開發</a><br>
 * Copyright (C), 2020, Li Weile<br>
 * This program is testing the funtion of javadoc. <br>
 * Program Name: test_javadoc <br>
 * Date: 2020-04-25 <br>
 * @author LiWeile [email protected]
 * @version 1.0
 */
public class Test
{
	/**
	 * 簡單測試成員變量
	 */
	public int age;
	/**
	 * Test 類的測試構造器
	 */
	public Test()
	{
	}
}

（三）輸入javadoc命令

javadoc -d apidoc -windowtitle Test -doctitle learnJavadocTestAPIdocument -header my_class *Test.java

這裏一定要主意好空格，書裏面的有點印刷問題，會報錯。可以看到如下輸出，點開自己寫的包：


  這樣就可以看到自己的API文檔了，是有點兒牛逼的亞子。

javadoc命令的基本用法如下：

javadoc 選項 Java 源文件|包

javadoc命令可對源文件、包生成API文檔，在上面的語法格式中，Java源文件可以支持通配符，例如：使用 *.java 來代表當前路徑下所有的Java源文件。Javadoc的常用選項有如下幾個：

• -d ：該選項指定一個路徑，用於將生成的API文檔放到指定目錄下
• windowtitle:該選項指定一個字符串，用於設置API文檔的瀏覽器窗口標題
• doctitle：該選項指定一個HTML格式的文本，用於指定概述頁面的標題。（注意：只有對處於多個包下的源文件來生成API文檔時，纔有概述頁面）
• header:該選項指定一個HTML格式的文本，包含每個頁面的頁眉。
    除此之外，javadoc命令還包含了大量其他選項，讀者可以通過在命令行窗口執行javadoc -help 來查看javadoc 命令的所有選項。

  除此之外，如果希望javadoc工具生成更詳細的文檔信息，例如爲方法參數、方法返回值等生成詳細的說明信息，則可利用javadoc標記。常用的javadoc標記如下：

• @author：指定Java程序的作者
• @version：指定源文件的版本
• @deprecated：不推薦使用的方法
• @param：方法的參數說明信息
• @return：方法的返回值說明信息
• @see：“參見”，用於指定交叉參考的內容
• @exception：拋出異常的類型
• @throws：拋出的異常和@exception同義。
    需要指出的是：這些標記的使用是有位置限制的。上面這些標記可以出現在類或者接口文檔註釋中的有@see、@deprecated、@author、@version 等；可以出現在方法或構造器文檔註釋中的有@see、@deprecated、@param、@return、@throws、和@exception等。可以出現在成員變量的文檔註釋中有@see和@deprecated等。
    我們再寫一個文件，包含一個hello方法，該方法的文檔註釋使用了@param和@return等文檔標記。文件名叫JavadocTagTest.java

package yeeku;
/**
 * Description:
 * 網站：<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java語言概述與開發</a><br>
 * Copyright (C), 2020, Li Weile<br>
 * This program is testing the funtion of javadoc. <br>
 * Program Name: test_javadoc <br>
 * Date: 2020-04-25 <br>
 * @author LiWeile [email protected]
 * @version 1.0
 */
public class JavadocTagTest
{
	/**
	 * 一個得到打招呼字符串的方法
	 * @param name 該參數指定向誰打招呼
	 * @return 返回打招呼的字符串
	 */
	
	public String hello(String name)
	{
		return name + ",你好!";
	}
}

  上面程序中粗體字標識出使用javadoc標記的示範，再次使用javadoc工具來生成API文檔，這次爲了能夠提取到文檔中的@author 和@version 等標記信息，再使用javadoc 工具時增加-author 和 -version兩個選項，即按如下格式來運行：

javadoc -d apidoc -windowtitle 測試 -doctitle 學習 javadoc 工具c的測試API文檔 -header 我的類 -version -author *Test.java

可以看到：

  接下來還是使用上面編寫的三個java文件，但是把三個Java文件按包結構分開組織存放，並提供對應的包描述文件，源文件和對應包描述文件的組織結構如下：

• lee 文件夾：包含JavadocTest.java 文件（該Java類的包爲lee），對應描述包文件package.html
• yeeku 文件夾： 包含Test.java 文件和JavadocTagTest.java 文件（這兩個Java類的包爲yeeku），對應包描述文件package.html
  在命令行窗口進入lee和yeeku所在路徑（package路徑），執行如下：

javadoc -d apidoc -windowtitle 測試 -doctitle 學習javadoc工具的測試API文檔 -header 我的類 -version -author lee yeeku

  上面的命令指對lee包和yeeku包來生成API文檔，而不是對Java源文件來生成API文檔，這也是允許的。其中lee包和yeeku包下面都提供對應的包描述文件。打開頁面：

通常稍微大一點的軟件目錄一般都需要用最後這種API文檔生成的方法。記住即可。