Hey everyone, I'm trying to figure out how to add ...

# getting-started

[rad]

Hey everyone, I'm trying to figure out how to add a comment to a primary constructor without commenting the class. This is how I would usually do it:

public class SoundEvent(
    /** Whether this sound should replace vanilla's sound. */
    public val replaceVanilla: Boolean = true,
    /** The translation key of the subtitle that should be displayed. */
    public val subtitle: String? = null,
    /** The sound set of this sound event. */
    public val soundSet: MutableList<Key> = mutableListOf(),
)

But adding a comment to the constructor like this does not show in my IDE:

public class SoundEvent /** Some text */ public constructor(
    /** Whether this sound should replace vanilla's sound. */
    public val replaceVanilla: Boolean = true,
    /** The translation key of the subtitle that should be displayed. */
    public val subtitle: String? = null,
    /** The sound set of this sound event. */
    public val soundSet: MutableList<Key> = mutableListOf(),
)

I can add comments to secondary constructors, but not on primary ones. How can I do this?

[Michael Krussel]

The way you showed is how I normally do it and I see it when I do quick documentation.

But there is also the @constructor

/**
 * Class
 *
 * @constructor a constructor
 */

Everything after the @constructor applies to the constructor including @param and @param above it is the type parameters for the class.

[Michael Krussel]

After some experimenting, It seems if you don't put a new line between the class and the KDoc for the constructor it doesn't work. Detekt gives a warning.

[Michael Krussel]

public class SoundEvent 
/** Some text */ public constructor(
    /** Whether this sound should replace vanilla's sound. */
    public val replaceVanilla: Boolean = true,
    /** The translation key of the subtitle that should be displayed. */
    public val subtitle: String? = null,
    /** The sound set of this sound event. */
    public val soundSet: MutableList<Key> = mutableListOf(),
)

[rad]

I was going to stick to @constructor but that seems to apply to all constructors and not only the primary one. The solution you just showed looks pretty weird syntactically to be honest

[rad]

Plus it also does not show in the IDE. I'm primarily wanting to put a warning on the primary constructor for users without wanting to deprecate it

[Michael Krussel]

I would normally have the new line after the KDoc and the public constructor and it works correctly with Dokka.

What I'm finding is that if you do the documentation on the constructor and not using the @constructor then you see the documentation in quick documentation only if the class has no documentation, otherwise you see the class's documentation. The newlines don't make a difference.

I didn't use the @constructor or @property options in the class documentation because they don't export out to the objective-c headers.

But I do see the @constructor working in the IDE. Could be a version thing or something else causing bugs. I'm also surprised that the @constructor applies to all of them and not just the primary. Probably worth flagging a bug with Intallij. If you're using a different IDE, than all my advice is wrong.

[rad]

I am using intellij, but yeah, it seems like if I do not have a class KDoc, the constructor comment shows correctly. Is this a thing in Dokka too?

[Michael Krussel]

I don't think so. I think the IDE just doesn't know which one you want to show when you are calling the primary constructor, but if that was the case it shouldn't matter how you are declaring the constructor documentation. So I would consider this a bug.

My testing here was also when I was extending a class and bringing up the documentation.

[rad]

Okay so I just tried this.

/**
 * A list of sounds in a namespace, akin to a sounds.json.
 */
public class SoundList
/** This constructor does not initialize the namespace, so be careful using it. */
public constructor(
    /** The sound events in this sound list. */
    public var soundEvents: MutableList<SoundEvent>,
) : ResourcePackElement {
    public constructor(
        /** The namespace of this sound list. */
        namespace: String,
        /** The sound events in this sound list. */
        soundEvents: MutableList<SoundEvent> = mutableListOf(),
    ) : this(soundEvents) {
        this.namespace = namespace
    }
}

Dokka shows this:

[Michael Krussel]

That's no good