What is the proper way of documenting primary constructor parameters?

Language Design
1

How are primary constructor parameters supposed to be documented?
For example, there is a class:

class Foo(
    param0: Int,
    private val property0: Int,
    val property1: Int
)

There is 1 constructor parameter, 1 private property and 1 public property. How should they be documented? I mean, what is the recommended way?

For examle, I can do something like that:

/**
 * Class description
 * 
 * @constructor primary constructor description
 * @param param0 description of param0
 * @param property0 description of property0
 * @property property1 description of property1
 **/
class Foo(
    param0: Int,
    private val property0: Int,
    val property1: Int
)

But in this case public property is not shown in constructor documentation.

Alternatively, I can do like that:

/**
 * Class description
 * 
 * @constructor primary constructor description
 * @param param0 description of param0
 * @param property0 description of property0
 * @param property1 description of property1
 **/
class Foo(
    param0: Int,
    private val property0: Int,
    val property1: Int
)

In this case constructor parameters are not shown in class kdoc. Instead, they are only visible in constructor kDoc.
I understand, that generally speaking this is correct, but in practice that is inconvenient.
Finally, I can remove constructor tag:

/**
 * Class description
 * 
 * @param param0 description of param0
 * @param property0 description of property0
 * @param property1 description of property1
 **/
class Foo(
    param0: Int,
    private val property0: Int,
    val property1: Int
)

But in this case constructor kDoc displays generic arguments of the class (in case there are any).
I failed to find answers to these quesions in kDoc documentation.
So my question is: what is the recommended way of writing class kDoc?

1 Like
2

According to Document Kotlin code: KDoc and Dokka | Kotlin it’s @param for parameters and @property for properties. They suggest keeping @costructor.

3

That example in documentation is not full.
Namely:

  1. They only have example of generic argument. What about constructor parameters? I believe, constructor parameters are a different thing. Should @param tag be placed under @constructor tag or before it? These 2 strategies have different semantics.
  2. property in the example is public. How should private properties which are declared in constructor be documented? As @param or @property? I have my opinion about it, but would like to have official recommendation.