Let's say you have the following class ```class Ex...

# random

[Edoardo Luppi]

Let's say you have the following class

class Example(
  private val one: String,
  private val two: Int,
) { ... }

Are you going to document these private properties using KDoc's @param or @property?
For example

/**
 * @property one One
 * @property two Two
 */
class Example(
  private val one: String,
  private val two: Int,
) { ... }

[Klitos Kyriacou]

I would probably document them as @param because the fact they're properties is an implementation detail, as they're private, and so it shouldn't be documented.

[Edoardo Luppi]

Thanks!

Imagine those properties become public, you now also need to remember to switch to @property, or the opposite.
Feels like DevEx's gone wrong here.

[Sam]

I just do this:

class Example(
  /** One */
  private val one: String,
  /** Two */
  private val two: Int,
) {}

Best of both worlds 👍

[Edoardo Luppi]

That's what I also did, however, you'll notice that parameter documentation will not be present for the constructor : (

[Sam]

Oh, I see the problem 😞 that's frustrating

[Oleg Yukhnevich]

I see the frustration, but I also can see the reason for this.

Do you have any idea on how to improve this? 🙂
F.e I think, that:

Imagine those properties become public, you now also need to remember to switch to @property, or the opposite.

Feels like DevEx's gone wrong here.

Could be solved by tooling (IDEA/Dokka)

Otherwise, both tags have different use-cases and are shortcuts for primary constructor documentation, so I think it's fine if they work in most cases.
Anyway, would be nice to hear how it could be improved

[Edoardo Luppi]

@Oleg Yukhnevich

Do you have any idea on how to improve this?

My only idea, and what I think would work best both for Dokka and in-IDE documentation, is treating KDoc specified on the parameter as @property or @param depending on how that parameter is declared.

For example:

class Example(
  /** My doc */
  private val s: String,
)

This is a private property, so this can be inferred as @param, showing its documentation both when accessing that property, and also when showing the constructor's documentation.

class Example(
  /** My doc */
  val s: String,
)

This can be inferred as @property

class Example(
  /** My doc */
  s: String,
)

And this as @param

[Oleg Yukhnevich]

okay, then, what about this:

fun someFunction(
  /** My doc */
  s: String
) {}

Should we then support this? I mean, for consistency, if we support documenting parameters for constructors, so probably it's possible to do it for constructors
I'm not sure that this is something that should be supported TBH

Overall, I agree, that there is a confusion with regards to @param vs @property and overall documentation of primary constructor, but in most cases there is a clear separation on when to use one or another and we need to be careful not to complicate things because of some edge case

And IMO, in this case, the only inconvenience is when switching the visibility of the property (you need to change tag). But in case of changing visibility, probably you will want not only just change tag, but also change documentation.
For now, I'm not sure, that this a big problem, but for sure there is a place for improvements

[Edoardo Luppi]

I think my problem is there are too many ways to do it for primary ctor docs. IMO the goal should be to find a single way, so we don't end up with erroneous docs and different styles everywhere.

[Oleg Yukhnevich]

I think my problem is there are too many ways to do it for primary ctor docs. IMO the goal should be to find a single way, so we don't end up with erroneous docs and different styles everywhere.

I get it and I feel it. Still, it's there to make documentation experience a bit better
Let's check following examples:
1: why @param is possible for class:

/**
 * documentation for class
 *
 * @param p documentation for parameter of constructor
 */
class A(p: String)

/**
 * documentation for class
 */
class B
/**
 * @param p documentation for parameter of constructor
 */
constructor(p: String)

2: why @property is useful

/**
 * documentation for class
 *
 * @property p documentation for property
 */
class A(val p: String)

/**
 * documentation for class
 */
class B(
    /**
     * documentation for property
     */
    val p: String
)

3: confusing combination

/**
 * documentation for class
 *
 * @param p documentation for param
 * @property p documentation for property
 */
class A(val p: String)

/**
 * documentation for class
 */
class B
/**
 * @param p documentation for param
 */
constructor(
    /**
     * documentation for property
     */
    val p: String
)

in the end, I think, the question is: do you really want to document a lot of parameters of constructor/function? In most cases, it's better to integration parameters description into overall KDoc for declaration. in case of constructor there is a tag @constructor, again, the idea for it is similar to examples above - to reduce amount of documentation comments to document class main characteristics
Also, you probably not always want to have the same documentation for both @param and @property , e.g in case you want to describe some specific validation for constructor param

May be it's not ideal, may be we just need to have some kind of guidelines, but still, there are cases where different tags are needed and it's hard to make it one-size-fits-all...

[Sam]

Personally, I always prefer putting a doc comment on each individual declaration (property, parameter, etc). That way, it's easier to find and much more likely to stay up-to-date. If I put them on the class, I just forget about them. Docs should always live as close as possible to the thing they're describing.

[Edoardo Luppi]

Agree. That's why moving to using @param from simply having the KDoc on the ctor property was a bit painful.
I'm very careful when refactoring, but that's absolutely not the case for everyone