CODEWITHSUNDEEP
kotlindocumentationkotlin-dokka
Lore
Lore

Reputation: 1938

Using KDoc to document group of variables

So I have this group of constants in a 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"

When I execute dokka, the comment associated to the constants doesn't format correctly in the docs... how can I use one description for multiple constants?

Upvotes: 1

Views: 1234

Answers (2)

IlyaMuravjov
IlyaMuravjov

Reputation: 2502

You can group elements in kDoc by grouping them in the code:

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

Upvotes: 1

gidds
gidds

Reputation: 18597

I don't think you can; doc comments (both JavaDoc and KDoc/Dokka) apply only to the following class/method/field/function/property.

If you really wanted them to have the same doc, I think you'd have to repeat the doc comment before each item.

Although this is ugly duplication, you can avoid wasting too much space by using the one-line form of comment (which I prefer to do for fields anyway):

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

That of course gives you the opportunity to say something specific about each field, which would be a better use of the docs, and justify the comments!

If there's really nothing to be said about each one, you could reduce the duplication by linking them all back to the first, e.g.:

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

Meanwhile, a comment that applies to all the fields together should probably be a non-doc comment:

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

(It could of course use the /* … */ format, but // is less likely to be confused with a doc comment.)

Upvotes: 1

Related Questions