Alternate KDoc comment style?

Language Design
1

Kotlin is awesome. The syntax is quite succinct, feels very modern. The only thing that irks me is the JavaDoc style comment syntax. Generally KDoc has brought some improvements, for example the square bracket links replacing these horrible {@link ...} annotations (ugh…). And luckily there is no XML (looking at you, C#). But these multi-line comment blocks seem wasteful, compared to the overall efficiency of Kotlin code:

/**
 * Welcoming words for new Kotlin programmers.
 */
val greeting: String

I think it would be great, if Kotlin would go the Dart way and allow a second comment style:

/// Welcoming words for new Kotlin programmers.
val greeting: String

Multi-line comment:

/// Welcoming words for new Kotlin programmers.
///
/// These words are shown to new Kotlin users when they open the program 
/// for the very first time.
val greeting: String

Two fewer lines needed per member. Also, no multi-line comment syntax (/* */) needed, which tends to get in the way more often than the single line syntax (//).

The following style is of course already possible, but /** has more visual noise than /// in my opinion, requires the ending */ sequence, and is also only feasible for a single line of text:

/** Welcoming words for new Kotlin programmers. */
val greeting: String

Now I know, this is a very minor issue. Some might claim screen estate is not that relevant anymore. This is completely anecdotal evidence, but I feel larger classes are harder to scan when the first style is used.

The biggest drawback that I can see right now is that there would be more than one way of doing the same thing, which can lead to inconsistencies. I must admit I have not thought this through. I just wanted to throw it out there and get some opinions.

Regards, Lukas

Edit: I just realized how beautifully the three character /// aligns with var, val, or fun.

7 Likes
2

This is a bike-shedding topic if there ever was one! :slight_smile:

Personally I like the consistency of the single-line style /** foo */ with the multi-line style. And it lines up with var, val, and fun too!

1 Like
3

Just goes to show how happy I am with the rest of the language. :smiley:

Also, just if it wasn’t obvious: This extends to multi-line comments. I added an example in the original post.

4

How about // for kdoc and /// for the rarer case of a comment that shouldn’t become documentation. Or, make comment style a configurable option for the user.

Rob

5

Just my two cents here,
I have extensively documented the Kodein source code, to make sure it is as understandable as possible.
Like @Lukas_Eibensteiner, I feel that using /// instead of /** ... */ would make the code more compact and therefore more readable.
Example : KodeinAware.kt

Salomon.

6

Resurrecting an old topic here, but a huge advantage of the /// style, which I don’t believe has been mentioned previously, is the ability to block comment a bunch of code (Select, Ctrl-Shift-/), and not have the block comment terminate and restart around each existing block / kdoc comment. If doing this today, IntelliJ IDEA reports:

Selected region contained block comments, surrounding ranges were commented

and then uncommenting the block later is a pain-in-the-butt.

The /// style would neatly solve this problem.

1 Like
7

I feel a need to weigh in here. I by far prefer the /** ... */ syntax. OP mentioned less visual noise, but actually i would argue the opposite: for readable, clean code good whitespacing is imperative! The empty first and last lines are visual whitespace buffers that helps break up large sections of code and makes them easier to read and navigate imo.