使用 KDoc 记录变量组

Question

所以我在 伴随对象中有这组常量:

        /**
         * 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

我认为你做不到；文档注释（JavaDoc 和 KDoc/Dokka）仅适用于以下 class/method/field/function/property.

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

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

/** 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"

这当然让您有机会针对每个领域说些具体的事情，这样可以更好地利用文档，并证明评论的合理性！

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

/** 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

您可以通过在 code:

中对 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"
}

使用 KDoc 记录变量组

Using KDoc to document group of variables

documentation

kotlin

kotlin-dokka