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 Likes
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

5 Likes
3

Try out BugKotlinDocument - IntelliJ IDEs Plugin | Marketplace

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.

1 Like
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.

11 Likes
6

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.

Might have worked that way in the past, but doesn’t for me (in terms of autocomplete). While the IDE will recognize params written immediately after @param in its highlighting, I find that autocomplete only works when using KDoc’s parameter referencing syntax [param].

7

The presence of this idea in a discussion is an indication of an unexperienced developer.

8

I don’t think so, a development tool should go along with the users’ wishes.

If a user wants to add comments for parameters the ide should support this, it’s supported for java so far so it shouldn’t be so complicated to support this for Kotlin too.

Additional descriptions of functions and parameters additional to meaningful names is a good idea, as I think

1 Like