編寫Kotlin代碼文檔

用來編寫 Kotlin 代碼文檔的語言(相當於 Java 的 JavaDoc)稱爲 KDoc。本質上 KDoc
是將 JavaDoc 的塊標籤(block tags)語法(擴展爲支持 Kotlin 的特定構造)和 Markdown 的
內聯標記(inline markup)結合在一起。

生成文檔

Kotlin 的文檔生成工具稱爲 Dokka。其使用說明請參見
Dokka README。

Dokka 有 Gradle、Maven 和 Ant 的插件，因此你可以將文檔生成集成到你的構建過程中。

KDoc 語法

像 JavaDoc 一樣，KDoc 註釋也以 /** 開頭、以 */ 結尾。註釋的每一行可以以
星號開頭，該星號不會當作註釋內容的一部分。

按慣例來說，文檔文本的第一段(到第一行空白行結束)是該元素的
總體描述，接下來的註釋是詳細描述。

每個塊標籤都以一個新行開始且以 @ 字符開頭。

以下是使用 KDoc 編寫類文檔的一個示例：

/**
 * 一組*成員*。
 *
 * 這個類沒有有用的邏輯; 它只是一個文檔示例。
 *
 * @param T 這個組中的成員的類型。
 * @property name 這個組的名稱。
 * @constructor 創建一個空組。
 */
class Group<T>(val name: String) {
    /**
     * 將 [member] 添加到這個組。
     * @return 這個組的新大小。
     */
    fun add(member: T): Int { …… }
}

塊標籤

KDoc 目前支持以下塊標籤(block tags)：

[@param](https://github.com/param "@param") <名稱>

用於函數的值參數或者類、屬性或函數的類型參數。
爲了更好地將參數名稱與描述分開，如果你願意，可以將參數的名稱括在
方括號中。因此，以下兩種語法是等效的：

@param name 描述。
@param[name] 描述。

[@return](https://github.com/return "@return")

用於函數的返回值。

[@constructor](https://github.com/constructor "@constructor")

用於類的主構造函數。

[@receiver](https://github.com/receiver "@receiver")

用於擴展函數的接收者。

[@property](https://github.com/property "@property") <名稱>

用於類中具有指定名稱的屬性。這個標籤可用於在
主構造函數中聲明的屬性，當然直接在屬性定義的前面放置 doc 註釋會很
彆扭。

[@throws](https://github.com/throws "@throws") <類>, [@exception](https://github.com/exception "@exception") <類>

用於方法可能拋出的異常。因爲 Kotlin 沒有受檢異常，所以
也沒有期望所有可能的異常都寫文檔，但是當它會爲類的用戶提供有用的信息時，
仍然可以使用這個標籤。

[@sample](https://github.com/sample "@sample") <標識符>

將具有指定限定的名稱的函數的主體嵌入到當前元素的文檔中，
以顯示如何使用該元素的示例。

[@see](https://github.com/see "@see") <標識符>

將到指定類或方法的鏈接添加到文檔的另請參見塊。

[@author](https://github.com/author "@author")

指定要編寫文檔的元素的作者。

[@since](https://github.com/since "@since")

指定要編寫文檔的元素引入時的軟件版本。

[@suppress](https://github.com/suppress "@suppress")

從生成的文檔中排除元素。可用於不是模塊的官方 API 的一部分
但還是必須在對外可見的元素。

KDoc 不支持 [@deprecated](https://github.com/deprecated "@deprecated") 這個標籤。作爲替代，請使用 [@Deprecated](https://github.com/Deprecated "@Deprecated") 註解。
{:.note}

內聯標記

對於內聯標記，KDoc 使用常規 Markdown 語法，擴展
了支持用於鏈接到代碼中其他元素的簡寫語法。

鏈接到元素

要鏈接到另一個元素(類、方法、屬性或參數)，只需將其名稱放在方括號中：

爲此目的，請使用方法 [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

另一個包中有用的東西。