Kotlin：属性设置器的文档

Question

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
        }

    ...
}

    /**
     * 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()都会出现上面的文档，因为在getter中有setter JavaDoc，在setter中有getter 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。

会很感激任何想法。

Answer 1

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

您应该记住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)
}