使用 Dokka 和 KDoc 生成 Kotlin 程式碼文檔

KDoc 是 document Kotlin 程式碼的語言，而 Dokka 是將 KDoc 生成文檔的引擎。Dokka 可以生成相當精美的 HTML 格式的文檔，另外還可以生成 Javadoc、Gfm 和 Jekyll 等格式的文檔。本文章將介紹如何在專案中使用 KDoc 和 Dokka。

完整程式碼可以在 下載。

KDoc

KDoc 是 document Kotlin 程式碼的語言，就相當於 Javadoc 是 document Java 程式碼的語言。KDoc 結合 Javadoc 和 Markdown。KDoc 支援 HTML 標籤，因為他繼承了 Javadoc 的語法。此外，還支援 Markdown，這是 Javadoc 沒有的。KDoc 使用 Javadoc 的 block tags，並額外新增幾個 block tags。

以下範例顯示幾個常用的 block tags。

• @constructor：Document primary constructor。
• @property：Document constructor 中的 property 參數。
• @param：Document constructor 和 function 中的參數。
• @return：Document 回傳值。
• @throws、@exception：Document 會被 method 丟出的 exception。因為 Kotlin 沒有 checked exception，所以不期望 Document 所有可能會被丟出的 exceptions。
• @see：See also 區塊。
• @sicne：開始支援的版本。
• @receiver：Document extension function。
• @suppress：不要將此 function 輸出到文檔中。
• @Deprecated：Document 此 function 為 deprecated。

值得注意的是，KDoc 沒有提供 block tag 來 document class 裡的 properties。這是因為你只要在 property 上方加上註解即可，不需要使用任何 block tag。

/**
 * A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T The type of a member in this group.
 * @property name The name of this group.
 * @param max The maximum number of total members.
 * @constructor Creates an empty group.
 */
class Group<T>(val name: String, max: Int) {
    /** All members */
    var members: List<T> = emptyList()
        private set

    /**
     * Adds a [member] to this group.
     * @param member The member to add.
     * @return The new size of the group.
     * @throws IllegalStateException If the number of the members is equal to the maximum.
     * @throws IllegalArgumentException If the given member does not have a name.
     * @see 1.0.0
     */
    fun add(member: T): Int { ... }

    /**
     * Search members in this group by a given name.
     * @param name The name to search.
     * @return All members that contains the given name.
     * @see add
     * @since 1.1.0
     */
    fun search(name: String): List<T> { ... }
}

/**
 * List all members' names containing the given name.
 * @receiver A string representing a name to search.
 * @return All members' names containing the given name.
 */
fun String.memberNames(): List<String> { ... }

Dokka

Dokka 是將 KDoc 生成文檔的引擎，就如同 Javadoc tool 是將 Javadoc 生成文檔的工具。而且，Dokka 也支援將 Javadoc 生成文檔。

Dokka 有兩種方式可以產生文檔，一種適用於 single-module project，另一種適用於 multi-module project。

Single-Module Project

Single-Module Project 是指專案中只有一個模組。首先，在 project level 的 build.gradle 中加入以下程式碼。如果你的是 Android 專案，則不需要額外加上 mavenCentral()。

plugins {
    id "org.jetbrains.dokka" version "1.7.20"
}

repositories {
    mavenCentral()
}

接下來，在 module level 的 build.gradle 中入以下程式碼。

plugins {
    id 'org.jetbrains.dokka'
}

最後，在專案下執行下面的指令，就會產生出文檔了。文檔預設會輸出在模組的 build/dokka 下面。Dokka 支援 dokkaHtml、dokkaJavadoc、dokkaGfm 和 dokkaJekyll tasks，分別生成 HTML、Javadoc、Gfm、Jekyll 格式的文檔。

AndroidDokkaExample % ./gradlew dokkaHtml

你可以改變文檔輸出的目錄。在 module level 的 build.gradle 中，設定文檔輸出的目錄。其他更多的設定，可以參照官網。

tasks.named("dokkaHtml") {
    outputDirectory.set(file("$rootProject.projectDir/docs/htmlMultiModule"))
}

Multi-Module Project

如果專案有多個模組，Dokka 可以將這些模組整合生成一個文檔。首先，在 project level 的 build.gradle 中加入以下程式碼。如果你的是 Android 專案，則不需要額外加上 mavenCentral()。

plugins {
    id "org.jetbrains.dokka" version "1.7.20"
}

repositories {
    mavenCentral()
}

接下來，在每個模組的 module level 的 build.gradle 中入以下程式碼。

plugins {
    id 'org.jetbrains.dokka'
}

以上的設定和單模組專案相同。不同的是，我們使用的 tasks 是 dokkaHtmlMultiModule、dokkaGfmMultiModule 和 dokkaJekyllMultiModule。

AndroidDokkaExample % ./gradlew dokkaHtmlMultiModule

你也可以改變文檔輸出的目錄。在 project level 的 build.gradle 中，設定文檔輸出的目錄。

tasks.named("dokkaHtmlMultiModule") {
    outputDirectory.set(file("$rootProject.projectDir/docs/htmlMultiModule"))
}

如果你希望 Dokka 排除某個模組的話，你就不要在那個模組的 build.gradle 中加上 org.jetbrains.dokka plugin 即可。

結語

Dokka 生成的 HTML 格式文檔相當地精美。KDoc 繼承了我們熟悉的 Javadoc 語法，還支援了好用的 Markdown。對筆者來說，這像是一個大大升級版的 Javadoc。