dokka ===== **_Note_: This is Google's fork of Dokka, customized for [Android API reference docs](https://developer.android.com/reference/) on [developer.android.com](https://developer.android.com/) and other Google products.** Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java. Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands standard Javadoc comments in Java files and [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in Kotlin files, and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown. ## Using Dokka ### Using the Gradle plugin ```groovy buildscript { repositories { jcenter() } dependencies { classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}" } } apply plugin: 'org.jetbrains.dokka' ``` The plugin adds a task named "dokka" to the project. Minimal dokka configuration: ```groovy dokka { outputFormat = 'html' outputDirectory = "$buildDir/javadoc" } ``` [Output formats](#output_formats) The available configuration options are shown below: ```groovy dokka { moduleName = 'data' outputFormat = 'html' outputDirectory = "$buildDir/javadoc" // These tasks will be used to determine source directories and classpath kotlinTasks { defaultKotlinTasks() + [':some:otherCompileKotlin', project("another").compileKotlin] } // List of files with module and package documentation // http://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation includes = ['packages.md', 'extra.md'] // The list of files or directories containing sample code (referenced with @sample tags) samples = ['samples/basic.kt', 'samples/advanced.kt'] jdkVersion = 6 // Used for linking to JDK // Use default or set to custom path to cache directory // to enable package-list caching // When set to default, caches stored in $USER_HOME/.cache/dokka cacheRoot = 'default' // Use to include or exclude non public members. includeNonPublic = false // Do not output deprecated members. Applies globally, can be overridden by packageOptions skipDeprecated = false // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions reportUndocumented = true skipEmptyPackages = true // Do not create index pages for empty packages impliedPlatforms = ["JVM"] // See platforms section of documentation // Manual adding files to classpath // This property not overrides classpath collected from kotlinTasks but appends to it classpath = [new File("$buildDir/other.jar")] // By default, sourceRoots is taken from kotlinTasks, following roots will be appended to it // Short form sourceRoots sourceDirs = files('src/main/kotlin') // By default, sourceRoots is taken from kotlinTasks, following roots will be appended to it // Full form sourceRoot declaration // Repeat for multiple sourceRoots sourceRoot { // Path to source root path = "src" // See platforms section of documentation platforms = ["JVM"] } // Specifies the location of the project source code on the Web. // If provided, Dokka generates "source" links for each declaration. // Repeat for multiple mappings linkMapping { // Source directory dir = "src/main/kotlin" // URL showing where the source code can be accessed through the web browser url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin" // Suffix which is used to append the line number to the URL. Use #L for GitHub suffix = "#L" } // No default documentation link to kotlin-stdlib noStdlibLink = false // Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka) // Repeat for multiple links externalDocumentationLink { // Root URL of the generated documentation to link with. The trailing slash is required! url = new URL("https://example.com/docs/") // If package-list file located in non-standard location // packageListUrl = new URL("file:///home/user/localdocs/package-list") } // Allows to customize documentation generation options on a per-package basis // Repeat for multiple packageOptions packageOptions { prefix = "kotlin" // will match kotlin and all sub-packages of it // All options are optional, default values are below: skipDeprecated = false reportUndocumented = true // Emit warnings about not documented members includeNonPublic = false } // Suppress a package packageOptions { prefix = "kotlin.internal" // will match kotlin.internal and all sub-packages of it suppress = true } } ``` To generate the documentation, use the `dokka` Gradle task: ```bash ./gradlew dokka ``` More dokka tasks can be added to a project like this: ```groovy task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) { outputFormat = 'javadoc' outputDirectory = "$buildDir/javadoc" } ``` Please see the [Dokka Gradle example project](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/dokka-gradle-example) for an example. #### Android If you are using Android there is a separate Gradle plugin. Just make sure you apply the plugin after `com.android.library` and `kotlin-android`. ```groovy buildscript { repositories { jcenter() } dependencies { classpath "org.jetbrains.dokka:dokka-android-gradle-plugin:${dokka_version}" } } apply plugin: 'com.android.library' apply plugin: 'kotlin-android' apply plugin: 'org.jetbrains.dokka-android' ``` ### Using the Maven plugin The Maven plugin is available in JCenter. You need to add the JCenter repository to the list of plugin repositories if it's not there: ```xml jcenter JCenter https://jcenter.bintray.com/ ``` Minimal Maven configuration is ```xml org.jetbrains.dokka dokka-maven-plugin ${dokka.version} pre-site dokka ``` By default files will be generated in `target/dokka`. The following goals are provided by the plugin: * `dokka:dokka` - generate HTML documentation in Dokka format (showing declarations in Kotlin syntax); * `dokka:javadoc` - generate HTML documentation in JavaDoc format (showing declarations in Java syntax); * `dokka:javadocJar` - generate a .jar file with JavaDoc format documentation. The available configuration options are shown below: ```xml org.jetbrains.dokka dokka-maven-plugin ${dokka.version} pre-site dokka false data html some/out/dir default packages.md extra.md src/test/samples 6 false true true JVM src/main/kotlin src/main/kotlin JVM ${project.basedir}/src/main/kotlin http://github.com/me/myrepo #L false https://example.com/docs/ kotlin false true false ``` Please see the [Dokka Maven example project](https://github.com/JetBrains/kotlin-examples/tree/master/maven/dokka-maven-example) for an example. [Output formats](#output_formats) ### Using the Ant task The Ant task definition is also contained in the dokka-fatjar.jar referenced above. Here's an example of using it: ```xml ``` The Ant task supports the following attributes: * `outputDir` - the output directory where the documentation is generated * `outputFormat` - the output format (see the list of supported formats above) * `classpath` - list of directories or .jar files to include in the classpath (used for resolving references) * `samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag) * `moduleName` - the name of the module being documented (used as the root directory of the generated documentation) * `include` - names of files containing the documentation for the module and individual packages * `skipDeprecated` - if set, deprecated elements are not included in the generated documentation * `jdkVersion` - version for linking to JDK * `impliedPlatforms` - See [platforms](#platforms) section * `` - analogue of src, but allows to specify [platforms](#platforms) * `` - Per package options for package `kotlin` and sub-packages of it * `noStdlibLink` - No default documentation link to kotlin-stdlib * `` - linking to external documentation, packageListUrl should be used if package-list located not in standard location * `cacheRoot` - Use `default` or set to custom path to cache directory to enable package-list caching. When set to `default`, caches stored in $USER_HOME/.cache/dokka ### Using the Command Line To run Dokka from the command line, download the [Dokka jar](https://github.com/Kotlin/dokka/releases/download/0.9.10/dokka-fatjar.jar). To generate documentation, run the following command: java -jar dokka-fatjar.jar Dokka supports the following command line arguments: * `-output` - the output directory where the documentation is generated * `-format` - the [output format](#output-formats): * `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references) * `-samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag) * `-module` - the name of the module being documented (used as the root directory of the generated documentation) * `-include` - names of files containing the documentation for the module and individual packages * `-nodeprecated` - if set, deprecated elements are not included in the generated documentation * `-impliedPlatforms` - List of implied platforms (comma-separated) * `-packageOptions` - List of package options in format `prefix,-deprecated,-privateApi,+warnUndocumented;...` * `-links` - External documentation links in format `url^packageListUrl^^url2...` * `-noStdlibLink` - Disable documentation link to stdlib * `-cacheRoot` - Use `default` or set to custom path to cache directory to enable package-list caching. When set to `default`, caches stored in $USER_HOME/.cache/dokka ### Output formats * `html` - minimalistic html format used by default * `javadoc` - Dokka mimic to javadoc * `html-as-java` - as `html` but using java syntax * `markdown` - Markdown structured as `html` * `gfm` - GitHub flavored markdown * `jekyll` - Jekyll compatible markdown * `kotlin-website*` - internal format used for documentation on [kotlinlang.org](https://kotlinlang.org) ### Platforms Dokka can annotate elements with special `platform` block with platform requirements Example of usage can be found on [kotlinlang.org](https://kotlinlang.org/api/latest/jvm/stdlib/) Each source root has a list of platforms for which members are suitable. Also, the list of 'implied' platforms is passed to Dokka. If a member is not available for all platforms in the implied platforms set, its documentation will show the list of platforms for which it's available. ## Dokka Internals ### Documentation Model Dokka uses Kotlin-as-a-service technology to build `code model`, then processes it into `documentation model`. `Documentation model` is graph of items describing code elements such as classes, packages, functions, etc. Each node has semantic attached, e.g. Value:name -> Type:String means that some value `name` is of type `String`. Each reference between nodes also has semantic attached, and there are three of them: 1. Member - reference means that target is member of the source, form tree. 2. Detail - reference means that target describes source in more details, form tree. 3. Link - any link to any other node, free form. Member & Detail has reverse Owner reference, while Link's back reference is also Link. Nodes that are Details of other nodes cannot have Members. ### Rendering Docs When we have documentation model, we can render docs in various formats, languages and layouts. We have some core services: * FormatService -- represents output format * LocationService -- represents folder and file layout * SignatureGenerator -- represents target language by generating class/function/package signatures from model Basically, given the `documentation` as a model, we do this: ```kotlin val signatureGenerator = KotlinSignatureGenerator() val locationService = FoldersLocationService(arguments.outputDir) val markdown = JekyllFormatService(locationService, signatureGenerator) val generator = FileGenerator(signatureGenerator, locationService, markdown) generator.generate(documentation) ``` ## Building Dokka Dokka is built with Gradle. To build it, use `./gradlew build`. Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run Dokka. Here's how to import and configure Dokka in IntelliJ IDEA: * Select "Open" from the IDEA welcome screen, or File > Open if a project is already open * Select the directory with your clone of Dokka * Note: IDEA may have an error after the project is initally opened; it is OK to ignore this as the next step will address this error * After IDEA opens the project, select File > New > Module from existing sources and select the `build.gradle` file from the root directory of your Dokka clone * Use the default options and select "OK" * After Dokka is loaded into IDEA, open the Gradle tool window (View > Tool Windows > Gradle) and click on the top left "Refresh all Gradle projects" button * Verify the following project settings. In File > Settings > Build, Execution, Deployment > Build Tools > Gradle > Runner: * Ensure "Delegate IDE build/run actions to gradle" is checked * "Gradle Test Runner" should be selected in the "Run tests using" drop-down menu * Note: After closing and re-opening the project, IDEA may give an error message: "Error Loading Project: Cannot load 3 modules". Open up the details of the error, and click "Remove Selected", as these module `.iml` files are safe to remove.