KDoc 是 document Kotlin 程式碼的語言,而 Dokka 是將 KDoc 生成文檔的引擎。Dokka 可以生成相當精美的 HTML 格式的文檔,另外還可以生成 Javadoc、Gfm 和 Jekyll 等格式的文檔。本文章將介紹如何在專案中使用 KDoc 和 Dokka。
Table of Contents
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。