h2. KotlinDoc

KotlinDoc is the Kotlin equivalent of javadoc and is used to comment public APIs. Current recommendations for code that works nice with KotlinDoc are:

* use the Java style /*\* comments \*/ syntax
* first sentence is used for the summary of a class/function/property and the rest of the documentation is for the detailed section
* you can use either HTML tags or [markdown|http://daringfireball.net/projects/markdown/syntax#block] wiki markup for styling comments with bold, bullet lists, links and so forth
* for linking to packages, classes, functions & properties we support WikiLink notation as: *\[\[expression\]\]* where expression can be a package name, class name, className.function() or className.property
* try to include test code that is compiled and tested inside the documentation, rather than including source code inside comments which can soon get stale and typically isn't refactor-safe. You can include the source code of a function relative to your source file using the *@includeFunction* macro as shown below, giving the relative file and name of the function to be included. The function body will be included inside the comments.

Here are some [examples|https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/src/kotlin/JLangIterables.kt].

{jet}
/**
 * This is **bold**
 *
 * New paragraph using newlines.
 *
 * We can also support wiki links notation
 * for example [[List]] and [[Collection]] and [[java.util.Collection.size()]] will
 * generate hypertext links to classes
 *
 * @includeFunctionBody ../test/MyTest.kt someFunction
 */
fun anotherMethod(): Unit { ... }
{jet}