使用 KDoc 记录变量组

Question

所以我在 companion object 中有这组常量：

        /**
         * Lists that can be associated to various media elements
         */
        const val MEDIA_NAME = "Media_name"
        const val SONGS_IDS = "Songs_ids"
        const val GENRE_IDS = "Genres_ids"
        const val ARTISTS_IDS = "Artists_ids"

当我执行 dokka 时，与常量相关的注释在文档中的格式不正确...如何对多个常量使用一个描述？

Answer 1

我认为你不能； doc cmets（JavaDoc 和 KDoc/Dokka）仅适用于以下类/方法/字段/函数/属性。

如果您真的希望他们拥有相同的文档，我认为您必须在每个项目之前重复文档注释。

虽然这是丑陋的重复，但您可以通过使用单行注释形式来避免浪费太多空间（无论如何我更喜欢对字段这样做）：

/** List that can be associated to various media elements. */
const val MEDIA_NAME = "Media_name"
/** List that can be associated to various media elements. */
const val SONGS_IDS = "Songs_ids"
/** List that can be associated to various media elements. */
const val GENRE_IDS = "Genres_ids"
/** List that can be associated to various media elements. */
const val ARTISTS_IDS = "Artists_ids"

这当然让您有机会对每个领域进行具体说明，这样可以更好地使用文档，并证明 cmets 的合理性！

如果真的没有什么可说的，你可以通过将它们全部链接回第一个来减少重复，例如：

/** List that can be associated to various media elements. */
const val MEDIA_NAME = "Media_name"
/** See [MEDIA_NAME] */
const val SONGS_IDS = "Songs_ids"
/** See [MEDIA_NAME] */
const val GENRE_IDS = "Genres_ids"
/** See [MEDIA_NAME] */
const val ARTISTS_IDS = "Artists_ids"

同时，适用于所有字段的注释可能应该是非文档注释：

// Lists that can be associated to various media elements:
…

（当然可以使用/* … */ 格式，但// 不太可能与文档注释混淆。）

Answer 2

您可以通过在代码中对元素进行分组来对kDoc中的元素进行分组：

/**
 * Lists that can be associated to various media elements
 */
object Media {
    const val NAME = "Media_name"
    const val SONGS_IDS = "Songs_ids"
    const val GENRE_IDS = "Genres_ids"
    const val ARTISTS_IDS = "Artists_ids"
}