Создание комментариев метода/класса Kotlin

Как вы создаете комментарии для своих методов/классов? Просто введите:

/**

И нажатие кнопки ввода не работает в IntelliJ IDEA 2016.1.3

Кажется, что Докка заменил KDoc, но почему в IntelliJ нет поддержки? Или я что-то упускаю?

Уточнение: при вводе /** + введите, это генерируется:

/**
 *
 */

Но мне интересно, почему поколение @param и других не добавлено (например, IntelliJ для Java). Эти аннотации используются для документирования кода Котлина (https://kotlinlang.org/docs/reference/kotlin-doc.html)

Ответы

Ответ 1

@param и другие теги не генерируются, потому что рекомендуемый стиль документации для Kotlin относится к именам параметров из текста комментария doc с использованием синтаксиса [foo], а не для их документирования с использованием явных тегов @param. Вы можете проверить стандартную библиотечную документацию Kotlin, чтобы узнать, как этот стиль используется.

Ответ 2

Чтобы подробнее рассказать о @yole answer и @Charles A. comment, здесь приводится полное объяснение предпочтительного формата при создании KDocs и его отличий от JavaDocs.

Документация Kotlin здесь:

https://kotlinlang.org/docs/reference/coding-conventions.html#documentation-comments

... говорит:

Как правило, избегайте использования тегов @param и @return. Вместо этого включите описание параметров и возвращаемых значений непосредственно в комментарий к документации и добавьте ссылки на параметры, где бы они ни упоминались. Используйте @param и @return только тогда, когда требуется длинное описание, которое не укладывается в поток основного текста.

Избегайте этого:

/**
 * Returns the absolute value of the given number.
 * @param number The number to return the absolute value for.
 * @return The absolute value.
 */
fun abs(number: Int) = ...

Сделайте это вместо этого:

/**
 * Returns the absolute value of the given [number].
 */
fun abs(number: Int) = ...