在 KDoc 中記錄屬性

Question

我看到很多代碼，它們使用標簽@property來記錄屬性：

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

但我更喜歡在定義的地方記錄屬性：

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

這兩種方式是否等價？

Answer 1

查看文檔 Kotlin 代碼：

/**
 * 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 { ... }
}

在那里，他們解釋了@property的目的，如下所示：

記錄具有指定名稱的類的屬性。 此標記可用於記錄在主構造函數中聲明的屬性，在屬性定義之前直接放置文檔注釋會很尷尬。

因此，您的做法（問題中的第二個示例）是進入 KDoc 的正確方法。 @property唯一有意義的地方是主構造函數屬性。

請注意，即使在構造函數中，我們也可以去掉@property並改為：

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

最后一點更多是品味問題。 我個人從不使用@property ，它看起來像 java 風格，符合我的口味。