代码之家 › 专栏 › 技术社区 › cjurjiu

Kotlin:属性设置器文档

kdoc javadoc kotlin java

8

cjurjiu · 技术社区 · 8 年前

我正在写一个科特林图书馆。在其中一个课程中,我有以下内容:

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 (即打电话给设定者)。

现在,对于Kotlin项目,这不会是一个问题,因为我可以将额外的KDoc添加到 到期时间 财产本身,而且不会觉得不合适:

    /**
     * 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)
        }

    ...
}

只是在IDE中没有显示JavaDoc,对于Kotlin和;Java代码。

我没有找到明确的方法来分离Java visible getters的文档;中的setters KDoc reference 或者 Java interop page 。

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

如果您有任何想法,我将不胜感激。

1 回复 | 直到 8 年前

1

2

Brian MissL 8 年前

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

您应该使用 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)
}

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