Котлин: Документация для правообладателя

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
        }

    ...
}

Тем не мение, updateExpiry(long) имеет поведение, которое должно быть прозрачным для клиентов SessionWrapper если они модифицируют expiryTime (т.е. вызовите сеттер).

Теперь, для проектов 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 в установщике.

Попытка разделить документацию для двух методов доступа в Котлине следующим образом:

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

    ...
}

просто не показывает JavaDoc в IDE, как для кода Kotlin, так и для кода Java.

Я не нашел четкого способа попытаться отделить документы для видимых Java-методов получения и установки в справочнике KDoc или странице взаимодействия Java.

Я нахожу это довольно раздражающим, учитывая хорошее взаимодействие 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)
}

ИМХО Не следует ожидать, что совместимость Java с Kotlin приведет к коду, подобному коду Java. Он совместим на уровне байт-кода, не обязательно на уровне исходного кода и уровня Javadoc.