Alternate KDoc comment style?


#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.


#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!


#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.