Kotlin: Documentation for property setter

Question

I am writing a Kotlin library. In one of the classes, I have the following:

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
        }

    ...
}

However, updateExpiry(long) has a behaviour which should be transparent to the clients of SessionWrapper, if they modify expiryTime (i.e. call the setter).

Now, for Kotlin projects, this wouldn't be an issue, since I can just add the extra KDoc to the expiryTime property itself, and it wouldn't feel out of place:

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

But for Java projects, the documentation above would appear for both setExpiryTime(long) and getExpiryTime(), which feels off because I would have setter JavaDoc in the getter, and getter JavaDoc in the setter.

Trying to separate the documentation for the two accessors, in Kotlin, in the following way:

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

    ...
}

just shows no JavaDoc in the IDE, for both Kotlin & Java code.

I found no clear way of trying to separate the docs for Java-visible getters & setters in the KDoc reference or the Java interop page.

I find this pretty annoying, given Kotlin's good interop with Java.

Would appreciate any ideas.

Answer 1

I think you should reevaluate your class design, instead of trying to explain special behavior in documentation. This is usually a sign of code smell and maybe also a sign of bad testability.

You should model the class with the special behavior of updateExpiry() in mind. If this aspect is worth being transparent to client, it should probably be part of some kind of interface or protocol steps.

Without knowing the details of the rest of your software, the best I can come up with is to just make the setter private and add a separate function for updating 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's Java interoperability should not be expected to result in code that is just like Java code. It is compatible on the byte code level, not necessarily on the source code and Javadoc level.