# 編寫 Kotlin 代碼文檔 [TOC] 用來編寫 Kotlin 代碼文檔的語言（相當于 Java 的 JavaDoc）稱為 **KDoc**。本質上 KDoc是將 JavaDoc 的塊標簽（block tags）語法（擴展為支持 Kotlin 的特定構造）和 Markdown 的內聯標記（inline markup）結合在一起。 ## 生成文檔 Kotlin 的文檔生成工具稱為 [Dokka](https://github.com/Kotlin/dokka)。其使用說明請參見[Dokka README](https://github.com/Kotlin/dokka/blob/master/README.md)。 Dokka 有 Gradle、Maven 和 Ant 的插件，因此你可以將文檔生成集成到你的構建過程中。 ## KDoc 語法 像 JavaDoc 一樣，KDoc 注釋也以 `/**` 開頭、以 `*/` 結尾。注釋的每一行可以以星號開頭，該星號不會當作注釋內容的一部分。 按慣例來說，文檔文本的第一段（到第一行空白行結束）是該元素的總體描述，接下來的注釋是詳細描述。 每個塊標簽都以一個新行開始且以 `@` 字符開頭。 以下是使用 KDoc 編寫類文檔的一個示例： ```kotlin /** * 一組*成員*。 * * 這個類沒有有用的邏輯; 它只是一個文檔示例。 * * @param T 這個組中的成員的類型。 * @property name 這個組的名稱。 * @constructor 創建一個空組。 */ class Group<T>(val name: String) { /** * 將 [member] 添加到這個組。 * @return 這個組的新大小。 */ fun add(member: T): Int { …… } } ``` ## 塊標簽 KDoc 目前支持以下塊標簽（block tags）： #### `@param <名稱>` 用于函數的值參數或者類、屬性或函數的類型參數。 為了更好地將參數名稱與描述分開，如果你愿意，可以將參數的名稱括在方括號中。因此，以下兩種語法是等效的： ``` @param name 描述。 @param[name] 描述。 ``` #### `@return` 用于函數的返回值。 #### `@constructor` 用于類的主構造函數。 #### `@receiver` 用于擴展函數的接收者。 #### `@property <名稱>` 用于類中具有指定名稱的屬性。這個標簽可用于在主構造函數中聲明的屬性，當然直接在屬性定義的前面放置 doc 注釋會很別扭。 #### `@throws <類>`, `@exception <類>` 用于方法可能拋出的異常。因為 Kotlin 沒有受檢異常，所以也沒有期望所有可能的異常都寫文檔，但是當它會為類的用戶提供有用的信息時，仍然可以使用這個標簽。 #### `@sample <標識符>` 將具有指定限定的名稱的函數的主體嵌入到當前元素的文檔中，以顯示如何使用該元素的示例。 #### `@see <標識符>` 將到指定類或方法的鏈接添加到文檔的**另請參見**塊。 #### `@author` 指定要編寫文檔的元素的作者。 #### `@since` 指定要編寫文檔的元素引入時的軟件版本。 #### `@suppress` 從生成的文檔中排除元素。可用于不是模塊的官方 API 的一部分但還是必須在對外可見的元素。 > KDoc 不支持 `@deprecated` 這個標簽。作為替代，請使用 `@Deprecated` 注解。 ## 內聯標記 對于內聯標記，KDoc 使用常規 [Markdown](http://daringfireball.net/projects/markdown/syntax) 語法，擴展了支持用于鏈接到代碼中其他元素的簡寫語法。 ### 鏈接到元素 要鏈接到另一個元素（類、方法、屬性或參數），只需將其名稱放在方括號中： ``` 為此目的，請使用方法 [foo]。 ``` 如果要為鏈接指定自定義標簽（label），請使用 Markdown 引用樣式語法： ``` 為此目的，請使用[這個方法][foo]。 ``` 你還可以在鏈接中使用限定的名稱。請注意，與 JavaDoc 不同，限定的名稱總是使用點字符來分隔組件，即使在方法名稱之前： ``` 使用 [kotlin.reflect.KClass.properties] 來枚舉類的屬性。 ``` 鏈接中的名稱與正寫文檔的元素內使用該名稱使用相同的規則解析。 特別是，這意味著如果你已將名稱導入當前文件，那么當你在 KDoc 注釋中使用它時，不需要再對其進行完整限定。 請注意 KDoc 沒有用于解析鏈接中的重載成員的任何語法。 因為 Kotlin 文檔生成工具將一個函數的所有重載的文檔放在同一頁面上，標識一個特定的重載函數并不是鏈接生效所必需的。 ## 模塊和包文檔 作為一個整體的模塊、以及該模塊中的包的文檔，由單獨的 Markdown 文件提供，并且使用 `-include` 命令行參數或 Ant、Maven 和 Gradle 中的相應插件將該文件的路徑傳遞給 Dokka。 在該文件內部，作為一個整體的模塊和分開的軟件包的文檔由相應的一級標題引入。標題的文本對于模塊必須是“Module `<模塊名>`”，對于包必須是“Package `<限定的包名>`”。 以下是該文件的一個示例內容： ``` # Module kotlin-demo 該模塊顯示 Dokka 語法的用法。 # Package org.jetbrains.kotlin.demo 包含各種有用的東西。 ## 二級標題 這個標題下的文本也是 `org.jetbrains.kotlin.demo` 文檔的一部分。 # Package org.jetbrains.kotlin.demo2 另一個包中有用的東西。 ```