Taiwan Kotlin User Group

Logo

Taiwan Kotlin User Group 的網站,在台灣推廣 Kotlin 程式語言,舉辦相關活動。如果對 Kotlin 有興趣,想要多瞭解一些,歡迎來我們的社群一起聚會!

View My GitHub Profile

Kotlin KDoc 註解範例

/**
 * *members* 的集合
 *
 * 這個類別單純展示如何撰寫 KDoc 註解
 *
 * @param T 集合內元素的型態
 * @property name 集合的名稱
 * @constructor 建立空集合
 */
class Group<T>(val name: String) {
    /**
     * 在集合內增加新 [member]
     * @return 集合增加後的大小
     */
    fun add(member: T): Int { ... }
}

支援的標籤

KDoc 不支援 @deprecated 標籤

要標記某個元件為棄用

可以使用 @Deprecated 這個 Annotation Class

(參考 [[Kotlin Annotation Class 範例]])

Inline markup

KDoc 可以使用 Markdown 格式撰寫內文

/**
 * Markdown 範例
 *
 * 這段程式有**以下流程**
 * - 首先⋯⋯
 * - 接著⋯⋯
 * - 最後⋯⋯
 */

KDoc 支援直接用 [] 標記其他元件

像是類別、方法、屬性、參數的名稱

/**
 * Returns the value of this [Float] number as a [BigDecimal].
 *
 * The number is converted to a string and then the string is converted to a [BigDecimal].
 */
public inline fun Float.toBigDecimal()

實際案例

Ktor

Application KDoc 註解如下

/**
 * Represents configured and running web application, capable of handling requests.
 * It is also the application coroutine scope that is cancelled immediately at application stop so useful
 * for launching background coroutines.
 *
 * @param environment Instance of [ApplicationEnvironment] describing environment this application runs in
 */

針對內部方法

比方說 dispose()

也有 KDoc 註解說明該函數的邏輯

/**
 * Called by [ApplicationEngine] when [Application] is terminated
 */
public fun dispose()

想看更多範例嗎?

可以看看

加入 kotlin.tips 的 Kotlin 讀書會