黃階低級 - 《 Java 核心》- 4.9 文檔註釋 - 修改0次

1、文檔註釋

1、Java 包含一個很有用的工具，叫做 javadoc ， 可以由源代碼生成一個 Html 文檔。聯機 API 文檔也是通過對標準 Java 類庫源代碼運行 javadoc生成的。
2、如果在源代碼中添加專用的定界符 /** 開始的註釋，那麼很容易生成專業的文檔。
3.這種方法可以是代碼和註釋保存在同一個地方，防止丟失。更改代碼後，再次運行 javadoc 即可。

2、註釋的插入

javadoc 從下面幾個特性中抽取信息：

• 包
• 公有類與接口
• 公有的和受保護的構造器和方法

• 公有的和受保護的域

3、類註釋

1、類註釋必須在 import 語句之後，在類定義之前。
2、沒有必要再而每一行的開始加 * 號，但大部分 IDE 會這麼做，自動的。

import java.*;

/**
 * 這是一個 Employee 類
 * 
 * @author swll
 * @version 0.1
 */

public class Employee {
}

4、方法註釋

1、方法註釋必須放在方法之前，除了通用標記之外，還可以使用 @param ，@return ，@throws 等描述：

/**
* @param ...
* @return ...
* @throws ...
*/
public static int assignID() {
    int r = nextId;
    nextId++;
    return r;
}

5、域註釋

只需要對公共域建議註釋文檔，常只靜態常量，其他域建立了文檔會暴露信息。

6、通用註釋

7、包與概述註釋

!! 要想產生包註釋，需要在每個包目錄中添加一個單獨的文件 !!
兩種方法：

1. package.html 文件， body 中的內容會全部被提取出來。
2. package-info.java 文件，使用 /* 和 / ，界定外不可以有其他代碼。