47

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)

DenEwout
  • 885
  • 2
  • 10
  • 17
  • `/`+`*`+`*`+`ENTER` generates `/**\n * \n */` for me in 2016.1.3. Could you have some plugin causing issues? – mfulton26 Jun 24 '16 at 14:22
  • 1
    Hi yes, sorry I should clarify it does generate that but it does not generate the @params/@return documented here: https://kotlinlang.org/docs/reference/kotlin-doc.html edit: added clarification to question. – DenEwout Jun 24 '16 at 14:39
  • Possible duplicate of [Generate KDoc for methods in Android Studio](https://stackoverflow.com/questions/40574195/generate-kdoc-for-methods-in-android-studio) – Blue Feb 04 '19 at 15:32

2 Answers2

38

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) = ...
Sean Barbeau
  • 11,496
  • 8
  • 58
  • 111
25

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.

yole
  • 92,896
  • 20
  • 260
  • 197
  • 2
    Then why does the [Documenting Kotlin Code](https://kotlinlang.org/docs/reference/kotlin-doc.html) page have a list of all available tags? Am I really missing something here? – Daksh Sep 04 '17 at 05:16
  • The tags are available and supported, but not _recommended_ for use. – yole Sep 04 '17 at 09:05
  • 1
    I'd have to ask you to link me to the documentation which describes the documentation process as detailed as possible. Thanks! Because by the looks of the link I posted in my previous comment, it seemed to me that that was what the official Kotlin Documentation recommends to use. – Daksh Sep 06 '17 at 01:30
  • 6
    @Daksh For what it's worth, I found that documentation that is being referring to [here](https://kotlinlang.org/docs/reference/coding-conventions.html#documentation-comments). – Charles A. Feb 19 '18 at 20:58
  • I checked that link ("Kotlin standard library") but I don't see anything about commenting functions – user155 May 20 '19 at 07:11
  • Those are two different concepts. Including a parameter between brackets `[foo]` produces a linked text to the content's definition, you can use that with any type, variable, ... which is in the scope. `@param` is used to tag the definition of a parameter (mainly if this is a long definition). So `@param [foo] the parameter that comes before [bar]` would be a typical comment. `[foo]` can actually be used anywhere in the comment, not only in the `@param` section. – RedGlyph Apr 12 '21 at 18:12