用來編寫 Kotlin 代碼文檔的語言(相當(dāng)于 Java 的 JavaDoc)稱為 KDoc。本質(zhì)上 KDoc
是將 JavaDoc 的塊標(biāo)簽(block tags)語法(擴(kuò)展為支持 Kotlin 的特定構(gòu)造)和 Markdown 的
內(nèi)聯(lián)標(biāo)記(inline markup)結(jié)合在一起。

生成文檔

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

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

KDoc 語法

像 JavaDoc 一樣，KDoc 注釋也以 /** 開頭、以 */ 結(jié)尾。注釋的每一行可以以
星號開頭，該星號不會當(dāng)作注釋內(nèi)容的一部分。

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

每個塊標(biāo)簽都以一個新行開始且以 @ 字符開頭。

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

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

塊標(biāo)簽

KDoc 目前支持以下塊標(biāo)簽(block tags)：

@param <名稱>

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

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

@return

用于函數(shù)的返回值。

@constructor

用于類的主構(gòu)造函數(shù)。

@receiver

用于擴(kuò)展函數(shù)的接收者。

@property <名稱>

用于類中具有指定名稱的屬性。這個標(biāo)簽可用于在
主構(gòu)造函數(shù)中聲明的屬性，當(dāng)然直接在屬性定義的前面放置 doc 注釋會很
別扭。

@throws <類>, @exception <類>

用于方法可能拋出的異常。因為 Kotlin 沒有受檢異常，所以
也沒有期望所有可能的異常都寫文檔，但是當(dāng)它會為類的用戶提供有用的信息時，
仍然可以使用這個標(biāo)簽。

@sample <標(biāo)識符>

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

@see <標(biāo)識符>

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

@author

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

@since

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

@suppress

從生成的文檔中排除元素?？捎糜诓皇悄K的官方 API 的一部分
但還是必須在對外可見的元素。

KDoc 不支持 @deprecated 這個標(biāo)簽。作為替代，請使用 @Deprecated 注解。
{:.note}

內(nèi)聯(lián)標(biāo)記

對于內(nèi)聯(lián)標(biāo)記，KDoc 使用常規(guī) Markdown 語法，擴(kuò)展
了支持用于鏈接到代碼中其他元素的簡寫語法。

鏈接到元素

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

為此目的，請使用方法 [foo]。

如果要為鏈接指定自定義標(biāo)簽(label)，請使用 Markdown 引用樣式語法：

為此目的，請使用[這個方法][foo]。

你還可以在鏈接中使用限定的名稱。請注意，與 JavaDoc 不同，限定的名稱總是使用點字符
來分隔組件，即使在方法名稱之前：

使用 [kotlin.reflect.KClass.properties] 來枚舉類的屬性。

鏈接中的名稱與正寫文檔的元素內(nèi)使用該名稱使用相同的規(guī)則解析。
特別是，這意味著如果你已將名稱導(dǎo)入當(dāng)前文件，那么當(dāng)你在 KDoc 注釋中使用它時，
不需要再對其進(jìn)行完整限定。

請注意 KDoc 沒有用于解析鏈接中的重載成員的任何語法。 因為 Kotlin 文檔生成
工具將一個函數(shù)的所有重載的文檔放在同一頁面上，標(biāo)識一個特定的重載函數(shù)
并不是鏈接生效所必需的。

模塊和包文檔

作為一個整體的模塊、以及該模塊中的包的文檔，由單獨(dú)的 Markdown 文件提供，
并且使用 -include 命令行參數(shù)或 Ant、Maven 和 Gradle 中的相應(yīng)插件
將該文件的路徑傳遞給 Dokka。

在該文件內(nèi)部，作為一個整體的模塊和分開的軟件包的文檔由相應(yīng)的一級標(biāo)題引入
。標(biāo)題的文本對于模塊必須是“Module <模塊名>”，對于包必須是“Package <限定的包名>”。

以下是該文件的一個示例內(nèi)容：

# Module kotlin-demo

該模塊顯示 Dokka 語法的用法。

# Package org.jetbrains.kotlin.demo

包含各種有用的東西。

## 二級標(biāo)題

這個標(biāo)題下的文本也是 `org.jetbrains.kotlin.demo` 文檔的一部分。

# Package org.jetbrains.kotlin.demo2

另一個包中有用的東西。