Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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)

like image 777
DenEwout Avatar asked Jun 24 '16 14:06

DenEwout


People also ask

How do you comment a function on Kotlin?

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.

How do you add comments on Kotlin?

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

Does Javadoc work with Kotlin?

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.

How do I use KDoc?

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.


2 Answers

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) = ... 
like image 117
Sean Barbeau Avatar answered Oct 28 '22 16:10

Sean Barbeau


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.

like image 39
yole Avatar answered Oct 28 '22 15:10

yole