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