Is `/** .. */` the only doc comments style availab...

# announcements

[vaskir]

Is /** .. */ the only doc comments style available? It's too verbose for single-line comments, see for example https://github.com/google/iosched/blob/master/model/src/main/java/com/google/samples/apps/iosched/model/Session.kt

[elizarov]

Why would you need docs comments in your app? Libraries I get it, but why would you pollute your app code? Look at data classes of KotlinConf app — it is clean & clear: https://github.com/JetBrains/kotlinconf-app/blob/develop/common/src/main/kotlin/org/jetbrains/kotlinconf/data/Speaker.kt

[vaskir]

For example, I'd like to see this comment https://github.com/JetBrains/kotlinconf-app/blob/develop/common/src/main/kotlin/org/jetbrains/kotlinconf/data/Speaker.kt#L5 in the tooltip.

[elizarov]

A reasonable ask. I would have helped me, too. Please, file a http://kotl.in/issue

[vaskir]

https://youtrack.jetbrains.com/issue/KT-27056

[elizarov]

OH GOD NO.

[elizarov]

There is no reason to

[elizarov]

Tooltips shall be just smart enough to show regular comments

[elizarov]

There is zero reason to force programmer to write an extra /.

[elizarov]

I have tons of code with private functions that have one-line // something comments before them. It is great idea to show those in tooltips

[vaskir]

why not? I find /** */ style noisy

[vaskir]

afaik it’s used in kotlin because it’s used in java?

[elizarov]

So, if you find it noisy, then why write ///. Just write // and let the tooling be smart enough to show those lines in tooltips.

[elizarov]

Why invent something new? Kotlin was specifically designed to be easy to learn for Java devs. Kotlin does not change what works well in Java without substantial reason behind it.

[elizarov]

On a philosophical note. You only need KDoc comments when you write a library and plan to publish its docs online. Take a look at stdlib and other Kotlin libs. These docs are almost never one-line. I find multi-line comments with /// extremely noisy. My eyes bleed when I read sources of C# standard library.

[vaskir]

hmm. Interesting 🙂 I'm a .net dev, never used java.

[vaskir]

(to make it clear, I'm not a C# dev 🙂 )

[elizarov]

I guessed that

[vaskir]

Anyway, I just stumbled upon https://github.com/google/iosched/blob/master/model/src/main/java/com/google/samples/apps/iosched/model/Session.kt and was surprised how noisy it is.

[elizarov]

That is I cannot help. This is just Java translated verbatim to Kotlin. It is not an idiomatic Kotlin code, which is clean and beautiful by design 🙂

[vaskir]

:)