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)
Just like with Javadoc, KDoc comments start with /** and end with */ . Every line of the comment may begin with an asterisk, which is not considered part of the contents of the comment.
Single-line comments starts with two forward slashes ( // ). Any text between // and the end of the line is ignored by Kotlin (will not be executed).
Just like Kotlin, Dokka fully supports cross-language Java/Kotlin projects. It can read Javadoc comments in Java code and KDoc comments in Kotlin code and generate documentation covering the entire API of a module, regardless of the language used to write each class in it.
For inline markup, KDoc uses the regular Markdown syntax, extended to support a shorthand syntax for linking to other elements in the code. To link to another element (class, method, property or parameter), simply put its name in square brackets: Use the method [foo] for this purpose.
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) = ...
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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With