Kotlin:财产制定者的文件

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
        }

    ...
}

但是,如果他们修改了(即调用setter),则updateExpiry(long)有一个对客户端应该是透明的行为.SessionWrapperexpiryTime

现在,对于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(),这感觉了,因为我会在吸气二传手的JavaDoc,并在二传手吸气的JavaDoc.

尝试以下列方式在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参考或Java互操作页面中尝试分离Java可见getter和setter的文档没有明确的方法.

考虑到Kotlin与Java的良好互操作,我觉得这很烦人.

会欣赏任何想法.

Answer 1

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

您应该考虑到特殊行为来对类进行建模updateExpiry()。如果这方面值得对客户端透明，那么它可能应该是某种接口或协议步骤的一部分。

在不知道软件其余部分的详细信息的情况下，我能想到的最好办法就是将设置器设为私有并添加一个单独的更新函数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 级别上兼容。