What will Markdown usage in Kotlin comments actually look like?


#1

I noticed this issue

http://youtrack.jetbrains.com/issue/KT-1452

and I recall a comment on the JetBrains blog that Kotlin will support Markdown for javadoc-like comments.

I’m curious what the the usage of Markdown in a Kotlin file will actually look like.  

Is there any example anyone can provide?

Thanks.


#2

Comments typically look like the Java equivalent by default; you can use HTML markup if you want as before

/** Some comment <b>this is bold</b> */ fun someMethod(): Unit { ... }

However if you want to use markdown notation you can add more concise bold, bullet lists, headers and links...

``

/** Some comment this is bold and a [link to something](http://something.com/foo) */
fun someMethod(): Unit { … }

We also support wiki links using [[someLink]] as shown below to be able to link to packages/classes/functions/properties (though currently other than some core JDK types, we only support fully qualified links so far)

``

/**

  • We can also support wiki links notation
  • for example [[List]] and [[Collection]] and [[java.util.Collection.size()]] will
  • generate hypertext links to classes
    */
    fun anotherMethod(): Unit { … }

If you pull the latest from github, do a build and run the maven build in the libraries directory, you’ll get the current KotlinDocs which shows the documentation in action

ant dist cd libraries mvn install open apidocs/target/apidocs/index.html

Note that currently we’re dependent on a snapshot build of the mvn plugin for the KDoc generation part; we can hopefully remove that limitation really soon!