Kotlin属性Setter文档编写：SessionWrapper类客户端透明性需求

我来分享下怎么给这个setter写符合要求的KDoc注释，核心是只向客户端暴露他们需要关心的信息，隐藏内部实现细节（也就是不让updateExpiry的存在被感知到）：

方式一：统一在属性主注释中说明Setter行为 #

这种写法适合getter和setter有相同约束（比如都要求主线程）的场景：

class SessionWrapper {
    /**
     * 会话的过期时长（单位：毫秒）。
     *
     * 设置该值会自动调整会话的过期逻辑，确保会话能够按照新的时长正确触发过期操作。
     *
     * @throws IllegalStateException 如果在非主线程调用该属性的getter或setter
     */
    var expiryTime = DEFAULT_EXPIRY_TIME
        get() {
            mainThreadCheck()
            return field
        }
        set(value) {
            mainThreadCheck()
            field = value
            updateExpiry(value)
        }
    // ... 其他成员
}

方式二：单独为Setter编写注释 #

如果想更清晰地区分getter和setter的行为，可以单独给setter块加注释：

class SessionWrapper {
    /**
     * 会话的过期时长（单位：毫秒）。
     *
     * @throws IllegalStateException 如果在非主线程调用该属性的getter
     */
    var expiryTime = DEFAULT_EXPIRY_TIME
        get() {
            mainThreadCheck()
            return field
        }
        /**
         * 设置会话的过期时长，系统会自动更新会话的过期机制以匹配新的时长。
         *
         * @param value 新的过期时长（单位：毫秒）
         * @throws IllegalStateException 如果在非主线程调用该setter
         */
        set(value) {
            mainThreadCheck()
            field = value
            updateExpiry(value)
        }
    // ... 其他成员
}

关键原则 #

1. 隐藏实现细节：不要在注释里提到updateExpiry方法，客户端不需要知道内部是怎么更新过期逻辑的，只需要知道设置这个值后，会话的过期规则会跟着生效就行。
2. 明确约束条件：必须告诉客户端这个属性的getter/setter只能在主线程调用，否则会抛出异常——这是客户端必须遵守的规则。
3. 聚焦实际效果：注释要说明设置该值会带来的实际影响（比如“调整会话过期逻辑”），而不是内部执行了什么操作。

内容的提问来源于stack exchange，提问作者cjurjiu