Kotlin - Documentation and Comments

• Just as Java has JavaDocs.
• And Ruby has RDoc.
• Kotlin has KDoc.

For creating comments that can be turned into documentation.

Basic Comments Syntax

Kotlin adopted Java comment syntax, which happens to line up with JavaScript comment syntax.

• // indicates that the rest of the line is a comment.

val foo = 0 // this is a comment.
// so is this

• /* and */ are used to delimit multiple lines as a comment.

val foo = 0 // this line has executable code
/*
val bar = 0 / this line does not, as it is wrapped in a comment.
*/

• The biggest - and perhaps only - difference between Kotlin comments and what you might do in Java is that multi-line comments can be nested in Kotlin.

/*
	It's
	/*
	  comments
	  /*
	    all 
	    /*
	      the
	      /*
	        way
	        /*
	          down!
             */
            */
           */
          */
         */
        */  

Introducing KDoc

If all that you want is add explanations to your code, to be read as part of that code, the comment syntax shown above is all you need.

• If you want to be able to generate standalone documentation for your code, the way that JavaDocs, RDocs, and similar tools do..Kotlin's equivalent is KDoc.

Basic KDoc Comments

• Just as JavaDoc comments start with /** and end with */, so too KDoc's comments:

/**
* This is a summary of your Kotlin class. It should explain, in a single
* paragraph, the role of this class in your project.
*
* Additional paragraphs after the first one should explain your class in
* greater detail. Of course, this class is extremely simple. It does not 
* need much in the way of explanation. Yet, for some reason, the author insists on keeping on typing text into this paragraph, as if his hand is
* guided by some unseen force. Or, perhaps, he is just trying to pad the
* paragraph out a bit.
*
* Oh, by the way, the line of asterisks that you see on the left is optional,
* as you will see in the function comment below.
*/

class Foo {
	/**
	This should explain what this function does.
		
	Um, that's it.
	*/
	fun something() = println("Hello, world!")
}

Formatting

• Where KDoc breaks from JavaDoc is in terms of text formatting.
• KDoc uses MarkDown, arguably the world' most popular "wikitext" markup language.
• KDoc lets you use Markdown formatting in your comments.
    So, you can use things like:
  • Boldface.
  • Italics.
  • Backticks wrapped around text to format it in monospace.
  • And so on.

Cross-Referencing

What Markdown lacks is a way to link to things inside the same document.

• Its hyperlink syntax works great for links to other pages.
• But NOT to material in the current page.
   
• KDoc extends Markdown linking syntax, allowing you to reference:
  • Properties.
  • Functions.
  • And similar named things by simple bracket syntax.

/**
* This the summary of your Kotlin class. It should explain, in a single 
* paragraph, the role of this class in your project.
*
* This class has a single function: [something]
*
* You can also link to other classes, such as [kotlin.String], using the fully-qualified class name.
*
* And, of course, you can [link to external content](https://commonsware.com).
*/
class Foo {
	/**
	This should explain what the function does.

	This function is inside of [Foo], as you can tell by looking up a few lines from where you are reading right now.
	*/
	fun something() = println("Hello, world!")
}

Block Tags

• As with JavaDoc, KDoc supports "block tags" for documenting sub-elements of class, function, etc.
• For example, you can use:
  • @param to document a function parameter.
  • @return to document a function return value, and so forth.

/**
* This is the summary of your Kotlin class. It should explain, in a single paragraph, the role of this class in your project.
*
* This class has a single function: [something].
*
* You can also link to other classes, such as [kotlin.String], using the fully-qualified class name.
*
* @author Mark Murphy
*/
class Foo {
	/**
	This should explain what this function does.

	This function is inside of [Foo], as you can tell by looking up a few lines from where you are reading right now.

	@param msg the message to be printed
	@return `true`, because, hey, why be negative?
	*/
	fun something(msg: String = "Hello, world!",) : Boolean {
		println(msg)
		return true
	}
}

Generating the Documentation

• Just as Java has a javadoc program to generate JavaDocs, and just as rdoc to generate documentation from RDocs comments, Kotlin has a similar tool: DOKKA.

Most likely, you will generate your documentation using the build system for your project, such as Gradle for an Android app project.

There is a way to generate the documentation from the command line, though Dokka does not seem optimized for that use case.