Kotlin：属性 setter 的文档

Question

我正在编写一个 Kotlin 库。在其中一个类中，我有以下内容：

class SessionWrapper {

    /**
     * The time in milliseconds after which the session will expire.
     */
    var expiryTime = DEFAULT_EXPIRY_TIME
        get() {
            mainThreadCheck()
            return field
        }
        set(value) {
            mainThreadCheck()
            field = value
            updateExpiry(value) <<< THIS ONE
        }

    ...
}

但是，updateExpiry(long) 的行为应该对 SessionWrapper 的客户端透明，如果他们修改 expiryTime（即调用 setter）。

现在，对于 Kotlin 项目，这不是问题，因为我可以将额外的 KDoc 添加到 expiryTime 属性本身，而且不会感觉不合适:

    /**
     * The time in milliseconds after which the session will expire.
     *
     * Updating the expiry time after the session is started does x,
     * the listeners will receive y.
     *
     * Writing comments is fun, when the tools work.
     */
     var expiryTime = DEFAULT_EXPIRY_TIME

但是对于 Java 项目，上面的文档会同时出现在 setExpiryTime(long) 和 getExpiryTime() 中，这感觉不对，因为我会有 setter Java文档在 getter 中，getter Java文档在 setter.

中

尝试在 Kotlin 中按以下方式分离两个访问器的文档：

class SomeClass{

    var expiryTime = DEFAULT_EXPIRY_TIME
        /**
         * The time in milliseconds after which the session will expire.
         */
        get() {
            mainThreadCheck()
            return field
        }
        /**
         * Updating the expiry time after the session is started does x,
         * the listeners will receive y.
         *
         * Writing comments is fun, when the tools work.
         */
        set(value) {
            mainThreadCheck()
            field = value
            updateExpiry(value)
        }

    ...
}

对于 Kotlin 和 Java 代码，

在 IDE 中没有显示 JavaDoc。

我没有找到明确的方法来尝试在 KDoc reference or the Java interop page 中分离 Java-可见 getters 和 setters 的文档。

考虑到 Kotlin 与 Java 的良好互操作性，我觉得这很烦人。

如有任何想法，我们将不胜感激。

Answer 1

我认为您应该重新评估您的 class 设计，而不是试图在文档中解释特殊行为。这通常是代码异味的标志，也可能是可测试性差的标志。

您应该为 class 建模，并牢记 updateExpiry() 的特殊行为。如果这方面值得对客户端透明，它可能应该是某种接口或协议步骤的一部分。

在不知道你软件其余部分的细节的情况下，我能想到的最好办法就是将 setter 设为私有并添加一个单独的函数来更新 expiryTime:

/** Explain property */
var expiryTime = DEFAULT_EXPIRY_TIME
    get() {
        mainThreadCheck()
        return field
    }
    private set(value) {
        mainThreadCheck()
        field = value
    }

/** Explain update behavior constraints */
fun updateExpiryTime(value: Any) {
  expiryTime = value
  updateExpiry(value)
}

恕我直言，Kotlin 的 Java 互操作性不应期望产生与 Java 代码类似的代码。它在字节码级别兼容，不一定在源代码和 Javadoc 级别兼容。

Kotlin：属性 setter 的文档

Kotlin: Documentation for property setter

java

kotlin

javadoc

kdoc