Why IntelliJ don't create automatically documentation comments for functions?


#1

Hey,
Usually, in Java, I used to typed /** + enter above some function, for example:

public int sum(int a, int b) {

and then it automatically created documentation comments, like:

/**
 *
 * @param a
 * @param b
 * @return
 */
 public int sum(int a, int b) {

But in kotlin, I’m typing /** and nothing happens…

Is it a problem in my settings or some misunderstanding?
Thanks.


#2

I believe it’s because of this convention:

Generally, avoid using @param and @return tags. Instead, incorporate the description of parameters and return values directly into the documentation comment

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


#3

Try out https://plugins.jetbrains.com/plugin/9781-bugkotlindocument


#4

Sorry, but your example comment looks pretty useless to me. Why should you generate such a useless comment? To satisfy company rules? Instead, use descriptive method and parameter names. That makes most function comments obsolete.

The presence of comments is an indication of bad source code.


#5

The presence of comments is an indication of bad source code.

Really? Please do not teach people bad practices even if you are using them yourself. Comments are needed even in the best code. Java/Kotlin programmer should also always remember, that there will be a lot of times, when users won’t read the code, but only use JavaDoc/KDoc for reference.

As for the first question, empty parameter comments are indeed not useful. It is usually better not to have them, than to have them blank. IDEA autocomplete works just fine with KDoc, meaning that you just have to start writing @param and the name after it and autocomplete will work.