Documenting properties in KDoc

Question

I see much code, which uses the tag @property to document properties:

/**
 * Some Class
 *
 * @property p Some property
 */
class C {
  val p = 42
}

But I prefer to document properties where the are defined:

/** Some Class */
class C {
  /** Some property */
  val p = 42
}

Are the two ways equivalent?

Answer 1

Have a look at Document Kotlin code:

/**
 * A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T the type of a member in this group.
 * @property name the name of this group.
 * @constructor Creates an empty group.
 */
class Group<T>(val name: String) {
    /**
     * Adds a [member] to this group.
     * @return the new size of the group.
     */
    fun add(member: T): Int { ... }
}

There, they explain the purpose of the @property like this:

Documents the property of a class which has the specified name. This tag can be used for documenting properties declared in the primary constructor, where putting a doc comment directly before the property definition would be awkward.

Thus, your way of doing (second example in your question) is the proper way to go in KDoc. The only place where @property makes sense is for primary constructor properties.

Note that even in constructor, we could get rid of the @property and write instead:

/**
 * ...
 */
class Group<T>(
  /** the name of this group. */
  val name: String
) {
    // ...
}

This last point is more a matter of taste. I personally never use @property, which looks to java-esque for my taste.