Generating Kotlin method/class comments

问题:

How do you generate comments for your methods/classes? Simply typing:

/**

And pushing enter does not seem to work in IntelliJ IDEA 2016.1.3

It seems like Dokka has superseded KDoc, but why is there no support in IntelliJ? Or am I missing something?

Clarification: when typing in /** + enter, this gets generated:

/**
 *
 */

But I'm wondering why the generation of @param and others aren't added (like IntelliJ does for Java). These annotations are used for documenting Kotlin code as well (https://kotlinlang.org/docs/reference/kotlin-doc.html)

回答1:

The @param and other tags are not generated because the recommended documentation style for Kotlin is to refer to parameter names from the doc comment text using the [foo] syntax, rather than to document them using explicit @param tags. You can check the Kotlin standard library documentation to see how this style is used.

回答2:

To expand on @yole's answer and @Charles A.'s comment, here is a full explanation of the preferred format when creating KDocs and how it differs from JavaDocs.

The Kotlin documentation here:

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

...says:

Generally, avoid using @param and @return tags. Instead, incorporate the description of parameters and return values directly into the documentation comment, and add links to parameters wherever they are mentioned. Use @param and @return only when a lengthy description is required which doesn't fit into the flow of the main text.

Avoid doing this:

/**
 * 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) = ...

Do this instead:

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