Revise documentation (#2728)

Co-authored-by: Sarah Haggarty <sarahhaggarty@users.noreply.github.com>

3 files changed, 781 insertions, 0 deletions

diff --git a/mkdocs/src/doc/docs/user_guide/applying/cli.md b/mkdocs/src/doc/docs/user_guide/applying/cli.md
new file mode 100644
index 00000000..3b02add2
--- /dev/null
+++ b/mkdocs/src/doc/docs/user_guide/applying/cli.md
@@ -0,0 +1,158 @@
+# Using command line
+
+To run Dokka from the command line, download the [Dokka CLI runner](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-cli).
+To generate documentation, run the following command:
+```
+java -jar dokka-cli.jar <arguments>
+```
+
+## Configuration options
+
+Dokka supports the following command line arguments:
+
+* `-outputDir` - the output directory where the documentation is generated
+* `-moduleName` - (required) - module name used as a part of source set ID when declaring dependent source sets
+* `-cacheRoot` - cache directory to enable package-list caching
+* `-pluginsClasspath` - artifacts with Dokka plugins, separated by `;`. At least `dokka-base` and all its dependencies must be added there
+* `-pluginsConfiguration` - configuration for plugins in format `fqPluginName=json^^fqPluginName=json...`
+* `-offlineMode` - do not resolve package-lists online
+* `-failOnWarning` - throw an exception instead of a warning
+* `-globalPackageOptions` - per package options added to all source sets
+* `-globalLinks` - external documentation links added to all source sets
+* `-globalSrcLink` - source links added to all source sets
+* `-noSuppressObviousFunctions` - don't suppress obvious functions like default `toString` or `equals`
+* `-suppressInheritedMembers` - suppress all inherited members that were not overriden in a given class. Eg. using it you can suppress toString or equals functions but you can't suppress componentN or copy on data class
+* `-sourceSet` - (repeatable) - configuration for a single source set. Following this argument, you can pass other arguments:
+    * `-sourceSetName` - source set name as a part of source set ID when declaring dependent source sets
+    * `-displayName` - source set name displayed in the generated documentation
+    * `-src` - list of source files or directories separated by `;`
+    * `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references) separated by `;`
+    * `-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) separated by `;`
+    * `-includes` - list of files containing the documentation for the module and individual packages separated by `;`
+    * `-includeNonPublic` - **Deprecated**, prefer using `documentedVisibilities`. Include protected and private code
+    * `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Overrides `includeNonPublic`. Default is `PUBLIC`. Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL` (Kotlin-specific), `PACKAGE` (Java-specific package-private)
+    * `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation
+    * `-reportUndocumented` - warn about undocumented members
+    * `-noSkipEmptyPackages` - create index pages for empty packages
+    * `-perPackageOptions` - list of package options in format `matchingRegex,-deprecated,-privateApi,+reportUndocumented;+visibility:PRIVATE;matchingRegex, ...`, separated by `;`
+    * `-links` - list of external documentation links in format `url^packageListUrl^^url2...`, separated by `;`
+    * `-srcLink` - mapping between a source directory and a Web site for browsing the code in format `<path>=<url>[#lineSuffix]`
+    * `-noStdlibLink` - disable linking to online kotlin-stdlib documentation
+    * `-noJdkLink` - disable linking to online JDK documentation
+    * `-jdkVersion` - version of JDK to use for linking to JDK JavaDoc
+    * `-analysisPlatform` - platform used for analysis, see the [Platforms](#platforms) section
+    * `-dependentSourceSets` - list of dependent source sets in format `moduleName/sourceSetName`, separated by `;`
+* `-loggingLevel` - one of `DEBUG`, `PROGRESS`, `INFO`, `WARN`, `ERROR`. Defaults to `DEBUG`. Please note that this argument can't be passed in JSON.
+
+
+You can also use a JSON file with Dokka configuration:
+ ```
+ java -jar <dokka_cli.jar> <path_to_config.json>
+ ```
+
+## Applying plugins
+To apply a Dokka plugin you have to provide it and all its dependencies in the `pluginsClasspath` parameter
+
+## Base plugin
+
+Using CLI runner to generate default documentation requires providing all dependencies manually on classpath.
+For Base plugins these are:
+
+* [dokka-base.jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-base)
+* [dokka-analysis.jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-analysis)
+* [kotlin-analysis-compiler.jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-analysis-compiler)
+* [kotlin-analysis-intellij.jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-analysis-intellij)
+* [kotlinx-html-jvm.jar](https://mvnrepository.com/artifact/org.jetbrains.kotlinx/kotlinx-html-jvm?repo=kotlinx)
+
+All of them are published on maven central. Another dependencies of Base plugin (e.g. `kotlinx-coroutines-core` and so on) are already included in `dokka-cli.jar`.
+To get them on classpath one should add them via `pluginsClasspath` argument, e. g.
+```
+java -jar dokka-cli.jar -pluginsClasspath "dokka-base.jar;dokka-analysis.jar;kotlin-analysis-compiler.jar;kotlin-analysis-intellij.jar;kotlinx-html-jvm.jar" ...
+```
+
+## Example using JSON
+
+To run Dokka with JSON configuration:
+```
+java -jar dokka-cli.jar dokkaConfiguration.json
+```
+Option values of JSON correspond to [Gradle ones](../../gradle/usage#configuration-options).
+The content of JSON file ```dokkaConfiguration.json```:
+```json
+{
+  "moduleName": "Dokka Example",
+  "moduleVersion": null,
+  "outputDir": "build/dokka/html",
+  "cacheRoot": null,
+  "offlineMode": false,
+  "sourceSets": [
+    {
+      "displayName": "jvm",
+      "sourceSetID": {
+        "scopeId": ":dokkaHtml",
+        "sourceSetName": "main"
+      },
+      "classpath": [
+        "libs/kotlin-stdlib-1.7.20.jar",
+        "libs/kotlin-stdlib-common-1.7.20.jar"
+      ],
+      "sourceRoots": [
+        "/home/Vadim.Mishenev/dokka/examples/cli/src/main/kotlin"
+      ],
+      "dependentSourceSets": [],
+      "samples": [],
+      "includes": [
+        "Module.md"
+      ],
+      "includeNonPublic": false,
+      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"],
+      "reportUndocumented": false,
+      "skipEmptyPackages": true,
+      "skipDeprecated": false,
+      "jdkVersion": 8,
+      "sourceLinks": [
+        {
+          "localDirectory": "/home/Vadim.Mishenev/dokka/examples/cli/src/main/kotlin",
+          "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example/src/main/kotlin",
+          "remoteLineSuffix": "#L"
+        }
+      ],
+      "perPackageOptions": [],
+      "externalDocumentationLinks": [
+        {
+          "url": "https://docs.oracle.com/javase/8/docs/api/",
+          "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
+        },
+        {
+          "url": "https://kotlinlang.org/api/latest/jvm/stdlib/",
+          "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list"
+        }
+      ],
+      "noStdlibLink": false,
+      "noJdkLink": false,
+      "suppressedFiles": [],
+      "analysisPlatform": "jvm"
+    }
+  ],
+  "pluginsClasspath": [
+    "plugins/dokka-base-1.7.20.jar",
+    "libs/kotlinx-html-jvm-0.7.3.jar",
+    "libs/dokka-analysis-1.7.20.jar",
+    "libs/kotlin-analysis-intellij-1.7.20.jar",
+    "libs/kotlin-analysis-compiler-1.7.20.jar"
+  ],
+  "pluginsConfiguration": [
+    {
+      "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
+      "serializationFormat": "JSON",
+      "values": "{\"separateInheritedMembers\":false,\"footerMessage\":\"© 2021 Copyright\"}"
+    }
+  ],
+  "modules": [],
+  "failOnWarning": false,
+  "delayTemplateSubstitution": false,
+  "suppressObviousFunctions": true,
+  "includes": [],
+  "suppressInheritedMembers": false
+}
+```
diff --git a/mkdocs/src/doc/docs/user_guide/applying/gradle.md b/mkdocs/src/doc/docs/user_guide/applying/gradle.md
new file mode 100644
index 00000000..435824f9
--- /dev/null
+++ b/mkdocs/src/doc/docs/user_guide/applying/gradle.md
@@ -0,0 +1,380 @@
+# Using the Gradle plugin
+
+!!! important
+    If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our
+    [migration guide](https://github.com/Kotlin/dokka/blob/master/runners/gradle-plugin/MIGRATION.md)
+
+### Supported versions
+Dokka should work on gradle newer than 5.6
+
+### Setup
+
+The preferred way is to use `plugins` block.
+
+build.gradle.kts:
+```kotlin
+plugins {
+    id("org.jetbrains.dokka") version "1.7.20"
+}
+
+repositories {
+    mavenCentral()
+}
+```
+
+You can also use the legacy plugin application method with `buildscript` block.
+Note that by using the `buildscript` way type-safe accessors are not available in Gradle Kotlin DSL,
+eg. you'll have to use `named<DokkaTask>("dokkaHtml")` instead of `dokkaHtml`:
+
+```kotlin
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}")
+    }
+}
+
+apply(plugin="org.jetbrains.dokka")
+```
+
+The plugin adds `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll` tasks to the project.
+
+Each task corresponds to one output format, so you should run `dokkaGfm` when you want to have a documentation in `GFM` format.
+Output formats are explained in [the introduction](../introduction.md#output-formats)
+
+If you encounter any problems when migrating from older versions of Dokka, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).
+
+Minimal configuration (with custom output directory only):
+
+Kotlin DSL
+```kotlin
+tasks.dokkaHtml.configure {
+    outputDirectory.set(buildDir.resolve("dokka"))
+}
+```
+
+
+Groovy DSL
+```groovy
+dokkaHtml {
+    outputDirectory.set(file("${buildDir}/dokka"))
+}
+```
+
+!!! note
+    Dokka extracts the information about sourcesets from the Kotlin Gradle plugin.
+    Therefore, if you are using Dokka in a [precompiled script plugin](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:precompiled_plugins),
+    you will have to add a depencency to the Kotlin Gradle Plugin as well
+    (`implementation(kotlin("gradle-plugin", "<kotlin-version>"))` resp. `implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:<kotlin-version>")`).
+
+## Configuration options
+
+Dokka documents single-platform as well as multi-platform projects.
+Most of the configuration options are set per one source set.
+The available configuration options are shown below:
+
+```kotlin
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.gradle.DokkaTask
+
+val dokkaHtml by getting(DokkaTask::class) {
+    outputDirectory.set(buildDir.resolve("dokka"))
+
+    // Set module name displayed in the final output
+    moduleName.set("moduleName")
+
+    // Use default or set to custom path to cache directory
+    // to enable package-list caching
+    // When this is set to default, caches are stored in $USER_HOME/.cache/dokka
+    cacheRoot.set(file("default"))
+
+    // Suppress obvious functions like default toString or equals. Defaults to true
+    suppressObviousFunctions.set(false)
+
+    // Suppress all inherited members that were not overriden in a given class. 
+    // Eg. using it you can suppress toString or equals functions but you can't suppress componentN or copy on data class. To do that use with suppressObviousFunctions
+    // Defaults to false
+    suppressInheritedMembers.set(true)
+
+    // Used to prevent resolving package-lists online. When this option is set to true, only local files are resolved  
+    offlineMode.set(false)
+    
+    dokkaSourceSets {
+        configureEach { // Or source set name, for single-platform the default source sets are `main` and `test`
+
+            // Used when configuring source sets manually for declaring which source sets this one depends on
+            dependsOn("otherSourceSetName")
+        
+            // Used to remove a source set from documentation, test source sets are suppressed by default  
+            suppress.set(false)
+
+            // Deprecated. Prefer using documentedVisibilities.
+            includeNonPublic.set(false)
+
+            // A set of visibility modifiers that should be documented
+            // If set by user, overrides includeNonPublic. Default is PUBLIC
+            documentedVisibilities.set(
+                setOf(
+                    DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier
+                    DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility
+                )
+            )
+
+            // Do not output deprecated members. Applies globally, can be overridden by packageOptions
+            skipDeprecated.set(false)
+
+            // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
+            reportUndocumented.set(true)
+
+            // Do not create index pages for empty packages
+            skipEmptyPackages.set(true)
+
+            // This name will be shown in the final output
+            displayName.set("JVM")
+
+            // Platform used for code analysis. See the "Platforms" section of this readme
+            platform.set(org.jetbrains.dokka.Platform.jvm)
+
+            // Property used for manual addition of files to the classpath
+            // This property does not override the classpath collected automatically but appends to it
+            classpath.from(file("libs/dependency.jar"))
+
+            // List of files with module and package documentation
+            // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
+            includes.from("packages.md", "extra.md")
+
+            // List of files or directories containing sample code (referenced with @sample tags)
+            samples.from("samples/basic.kt", "samples/advanced.kt")
+
+            // By default, sourceRoots are taken from Kotlin Plugin and kotlinTasks, following roots will be appended to them
+            // Repeat for multiple sourceRoots
+            sourceRoots.from(file("src"))
+
+            // Specifies the location of the project source code on the Web.
+            // If provided, Dokka generates "source" links for each declaration.
+            // Repeat for multiple mappings
+            sourceLink {
+                // Unix based directory relative path to the root of the project (where you execute gradle respectively). 
+                localDirectory.set(file("src/main/kotlin"))
+
+                // URL showing where the source code can be accessed through the web browser
+                remoteUrl.set(java.net.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
+                remoteLineSuffix.set("#L")
+            }
+
+            // Used for linking to JDK documentation
+            jdkVersion.set(8)
+
+            // Disable linking to online kotlin-stdlib documentation
+            noStdlibLink.set(false)
+
+            // Disable linking to online JDK documentation
+            noJdkLink.set(false)
+
+            // Disable linking to online Android documentation (only applicable for Android projects)
+            noAndroidSdkLink.set(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.set(URL("https://example.com/docs/"))
+
+                // If package-list file is located in non-standard location
+                // packageListUrl = URL("file:///home/user/localdocs/package-list")
+            }
+
+            // Allows to customize documentation generation options on a per-package basis
+            // Repeat for multiple packageOptions
+            // If multiple packages match the same matchingRegex, the longest matchingRegex will be used
+            perPackageOption {
+                // will match kotlin and all sub-packages of it
+                matchingRegex.set("kotlin($|\\.).*") 
+                
+                // All options are optional
+                skipDeprecated.set(false)
+                reportUndocumented.set(true) // Emit warnings about not documented members 
+                includeNonPublic.set(false) // Deprecated, prefer using documentedVisibilities
+
+                // Visibilities that should be included in the documentation
+                // If set by user, overrides includeNonPublic. Default is PUBLIC
+                documentedVisibilities.set(
+                    setOf(
+                        DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier
+                        DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility
+                    )
+                )
+            }
+            // Suppress a package
+            perPackageOption {
+                matchingRegex.set(""".*\.internal.*""") // will match all .internal packages and sub-packages 
+                suppress.set(true)
+            }
+
+            // Include generated files in documentation
+            // By default Dokka will omit all files in folder named generated that is a child of buildDir
+            suppressGeneratedFiles.set(false)
+        }
+        // Configures a plugin separately from the global configuration
+        pluginConfiguration<PluginClass, ConfigurationClass>{
+            // values
+        }
+    }
+}
+```
+
+## Multiplatform
+Dokka supports single-platform and multi-platform projects using source sets abstraction. For most mutli-platform projects
+you should assume that Dokka's source sets correspond to Kotlin plugin's source sets. All source sets are by default registered
+and configured automatically although test source sets are suppressed
+
+Kotlin
+```kotlin
+kotlin {  // Kotlin Multiplatform plugin configuration
+    jvm()
+    js("customName")
+}
+
+tasks.withType<DokkaTask>().configureEach {
+    // custom output directory
+    outputDirectory.set(buildDir.resolve("dokka"))
+
+    dokkaSourceSets { 
+         named("customNameMain") { // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically
+            includes.from("packages.md", "extra.md")
+            samples.from("samples/basic.kt", "samples/advanced.kt")
+        }
+
+        register("differentName") { // Different name, so source roots must be passed explicitly
+            displayName.set("JVM")
+            platform.set(org.jetbrains.dokka.Platform.jvm)
+            sourceRoots.from(kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs)
+            sourceRoots.from(kotlin.sourceSets.getByName("commonMain").kotlin.srcDirs)
+        }
+    }
+}
+```
+
+!!! note
+    If you want to share the configuration between source sets, you can use Gradle's `configureEach`
+
+## Applying plugins
+Dokka plugin creates Gradle configuration for each output format in the form of `dokka${format}Plugin` (or `dokka${format}PartialPlugin` for multi-module tasks) :
+
+```kotlin
+dependencies {
+    dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20")
+}
+``` 
+
+You can also create a custom Dokka task and add plugins directly inside:
+
+```kotlin
+val customDokkaTask by creating(DokkaTask::class) {
+    dependencies {
+        plugins("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20")
+    }
+}
+```
+
+!!! important
+    Please note that `dokkaJavadoc` task will properly document only single `jvm` source set
+
+To generate the documentation, use the appropriate `dokka${format}` Gradle task:
+
+```bash
+./gradlew dokkaHtml
+```
+
+Some plugins can be configured separately using a plugin class and configuration class. For example:
+
+```kotlin
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+
+pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+    customAssets = listOf(file("<path to asset>"))
+    customStyleSheets = listOf(file("<path to custom stylesheet>"))
+}
+```
+
+Keep in mind, that this only works when using a buildscript (with the configured plugin on classpath) since it is not possible to import plugin's class without it.
+For example, you can add `DokkaBase` to gain access to aforementioned configuration:
+
+```kotlin
+buildscript {
+    dependencies {
+        // classpath("<plugin coordinates>:<plugin version>")
+        classpath("org.jetbrains.dokka:dokka-base:1.7.20")
+    }
+}
+```
+
+If you don't want to use a buildscript or use Kotlin version lower than 1.3.50 you can achieve the same behaviour manually:
+```kotlin
+pluginsMapConfiguration.set(mapOf("<fully qualified plugin's name>" to """<json configuration>"""))
+```
+## Android
+
+!!! important
+    Make sure you apply Dokka after `com.android.library` and `kotlin-android`.
+
+```kotlin
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlin_version}")
+        classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}")
+    }
+}
+repositories {
+    mavenCentral()
+}
+apply(plugin= "com.android.library")
+apply(plugin= "kotlin-android")
+apply(plugin= "org.jetbrains.dokka")
+```
+
+```kotlin
+dokkaHtml.configure {
+    dokkaSourceSets {
+        named("main") {
+            noAndroidSdkLink.set(false)
+        }   
+    }
+}
+```
+
+## Multi-module projects
+For documenting Gradle multi-module projects, you can use `dokka${format}MultiModule` tasks.
+Dokka plugin adds `dokkaHtmlMultiModule`, `dokkaGfmMultiModule` and `dokkaJekyllMultiModule` tasks to
+all Gradle parent projects (all projects that have some child projects) as well as
+`dokkaHtmlPartial`, `dokkaGfmPartial` and `dokkaJekyllPartial` to all projects that have a parent.
+If you want eg. to add an external link to some dependency you should do so in respective `dokka${format}Partial` tasks,
+or configure them all at once using the `subprojects` block and `configureEach` method.
+
+```kotlin
+tasks.dokkaHtmlMultiModule.configure {
+    outputDirectory.set(buildDir.resolve("dokkaCustomMultiModuleOutput"))
+}
+```
+
+`DokkaMultiModule` depends on all Dokka tasks in the subprojects named `dokka${format}Partial`, runs them, and creates a top-level page
+with links to all generated (sub)documentations. It is possible to configure each of them:
+```kotlin
+tasks.dokkaHtmlPartial.configure {
+    failOnWarning.set(true)
+}
+```
+
+## Example projects
+
+Please see the [Dokka Gradle single module example project](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example) or [multimodule](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) for an example.
+
+Also see [generated documentation](https://Kotlin.github.io/dokka/examples/dokka-gradle-example/html) in `HTML` format.
diff --git a/mkdocs/src/doc/docs/user_guide/applying/maven.md b/mkdocs/src/doc/docs/user_guide/applying/maven.md
new file mode 100644
index 00000000..cde6e927
--- /dev/null
+++ b/mkdocs/src/doc/docs/user_guide/applying/maven.md
@@ -0,0 +1,243 @@
+# Using the Maven plugin
+
+!!! note
+    Dokka Maven plugin does not support multi-platform projects.
+
+Minimal Maven configuration is
+
+```xml
+<plugin>
+    <groupId>org.jetbrains.dokka</groupId>
+    <artifactId>dokka-maven-plugin</artifactId>
+    <version>${dokka.version}</version>
+    <executions>
+        <execution>
+            <phase>pre-site</phase>
+            <goals>
+                <goal>dokka</goal>
+            </goals>
+        </execution>
+    </executions>
+</plugin>
+```
+
+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
+
+## Configuration options
+
+The available configuration options are shown below:
+
+```xml
+<plugin>
+    <groupId>org.jetbrains.dokka</groupId>
+    <artifactId>dokka-maven-plugin</artifactId>
+    <version>${dokka.version}</version>
+    <executions>
+        <execution>
+            <phase>pre-site</phase>
+            <goals>
+                <goal>dokka</goal>
+            </goals>
+        </execution>
+    </executions>
+    <configuration>
+    
+        <!-- Set to true to skip dokka task, default: false -->
+        <skip>false</skip>
+    
+        <!-- Default: ${project.artifactId} -->
+        <moduleName>data</moduleName>
+
+        <!-- Default: ${project.basedir}/target/dokka -->
+        <outputDir>some/out/dir</outputDir>
+        
+        <!-- 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</cacheRoot>
+
+        <!-- Set to true to to prevent resolving package-lists online. -->
+        <!-- When this option is set to true, only local files are resolved, default: false -->
+        <offlineMode>false</offlineMode>
+
+        <!-- List of '.md' files with package and module docs -->
+        <!-- https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation -->
+        <includes>
+            <include>packages.md</include>
+            <include>extra.md</include>
+        </includes>
+
+        <!-- A list of visibility modifiers that should be documented -->
+        <!-- If set by user, overrides includeNonPublic. Default is PUBLIC -->
+        <documentedVisibilities>
+            <visibility>PUBLIC</visibility> <!-- Same for both kotlin and java -->
+            <visibility>PRIVATE</visibility> <!-- Same for both kotlin and java -->
+            <visibility>PROTECTED</visibility> <!-- Same for both kotlin and java -->
+            <visibility>INTERNAL</visibility> <!-- Kotlin-specific internal modifier -->
+            <visibility>PACKAGE</visibility> <!-- Java-specific package-private visibility (default) -->
+        </documentedVisibilities>
+        
+        <!-- List of sample roots -->
+        <samples>
+            <dir>src/test/samples</dir>
+        </samples>
+
+        <!-- Suppress obvious functions like default toString or equals. Defaults to true -->
+        <suppressObviousFunctions>false</suppressObviousFunctions>
+
+        <!-- Suppress all inherited members that were not overriden in a given class. -->
+        <!-- Eg. using it you can suppress toString or equals functions but you can't suppress componentN or copy on data class. To do that use with suppressObviousFunctions -->
+        <!-- Defaults to false -->
+        <suppressInheritedMembers>true</suppressInheritedMembers>
+
+        <!-- Used for linking to JDK, default: 6 -->
+        <jdkVersion>6</jdkVersion>
+
+        <!-- Do not output deprecated members, applies globally, can be overridden by packageOptions -->
+        <skipDeprecated>false</skipDeprecated> 
+        <!-- Emit warnings about not documented members, applies globally, also can be overridden by packageOptions -->
+        <reportUndocumented>true</reportUndocumented>             
+        <!-- Do not create index pages for empty packages -->
+        <skipEmptyPackages>true</skipEmptyPackages> 
+        
+        <!-- Short form list of sourceRoots, by default, set to ${project.compileSourceRoots} -->
+        <sourceDirectories>
+            <dir>src/main/kotlin</dir>
+        </sourceDirectories>
+        
+        <!-- Full form list of sourceRoots -->
+        <sourceRoots>
+            <root>
+                <path>src/main/kotlin</path>
+                <!-- See platforms section of documentation -->
+                <platforms>JVM</platforms>
+            </root>
+        </sourceRoots>
+        
+        <!-- Specifies the location of the project source code on the Web. If provided, Dokka generates "source" links
+             for each declaration. -->
+        <sourceLinks>
+            <link>
+                <!-- Source directory -->
+                <path>${project.basedir}/src/main/kotlin</path>
+                <!-- 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</url> <!-- //remove src/main/kotlin if you use "./" above -->
+                <!--Suffix which is used to append the line number to the URL. Use #L for GitHub -->
+                <lineSuffix>#L</lineSuffix>
+            </link>
+        </sourceLinks>
+        
+        <!-- Disable linking to online kotlin-stdlib documentation  -->
+        <noStdlibLink>false</noStdlibLink>
+        
+        <!-- Disable linking to online JDK documentation -->
+        <noJdkLink>false</noJdkLink>
+        
+        <!-- Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka) -->
+        <externalDocumentationLinks>
+            <link>
+                <!-- Root URL of the generated documentation to link with. The trailing slash is required! -->
+                <url>https://example.com/docs/</url>
+                <!-- If package-list file located in non-standard location -->
+                <!-- <packageListUrl>file:///home/user/localdocs/package-list</packageListUrl> -->
+            </link>
+        </externalDocumentationLinks>
+
+        <!-- Allows to customize documentation generation options on a per-package basis -->
+        <perPackageOptions>
+            <packageOptions>
+                <!-- Will match kotlin and all sub-packages of it -->
+                <matchingRegex>kotlin($|\.).*</matchingRegex>
+                
+                <!-- All options are optional, default values are below: -->
+                <skipDeprecated>false</skipDeprecated>
+                
+                <!-- Emit warnings about not documented members  -->
+                <reportUndocumented>true</reportUndocumented>
+                
+                <!-- Deprecated. Prefer using documentedVisibilities -->
+                <includeNonPublic>false</includeNonPublic>
+
+                <!-- A list of visibility modifiers that should be documented -->
+                <!-- If set by user, overrides includeNonPublic. Default is PUBLIC -->
+                <documentedVisibilities>
+                    <visibility>PUBLIC</visibility> <!-- Same for both kotlin and java -->
+                    <visibility>PRIVATE</visibility> <!-- Same for both kotlin and java -->
+                    <visibility>PROTECTED</visibility> <!-- Same for both kotlin and java -->
+                    <visibility>INTERNAL</visibility> <!-- Kotlin-specific internal modifier -->
+                    <visibility>PACKAGE</visibility> <!-- Java-specific package-private visibility (default) -->
+                </documentedVisibilities>
+            </packageOptions>
+        </perPackageOptions>
+        
+        <!-- Allows to use any dokka plugin, eg. GFM format   -->
+        <dokkaPlugins>
+            <plugin>
+                <groupId>org.jetbrains.dokka</groupId>
+                <artifactId>gfm-plugin</artifactId>
+                <version>${dokka.version}</version>
+            </plugin>
+        </dokkaPlugins>
+        
+        <!-- Configures a plugin separately -->
+        <pluginsConfiguration>
+            <fullyQualifiedPluginName>
+                <!-- Configuration -->
+            </fullyQualifiedPluginName>
+        </pluginsConfiguration>
+
+    </configuration>
+</plugin>
+```
+
+## Applying plugins
+You can add plugins inside the `dokkaPlugins` block:
+
+```xml
+<plugin>
+    <groupId>org.jetbrains.dokka</groupId>
+    <artifactId>dokka-maven-plugin</artifactId>
+    <version>${dokka.version}</version>
+    <executions>
+        <execution>
+            <phase>pre-site</phase>
+            <goals>
+                <goal>dokka</goal>
+            </goals>
+        </execution>
+    </executions>
+    <configuration>
+        <dokkaPlugins>
+            <plugin>
+                <groupId>org.jetbrains.dokka</groupId>
+                <artifactId>kotlin-as-java-plugin</artifactId>
+                <version>${dokka.version}</version>
+            </plugin>
+        </dokkaPlugins>
+    </configuration>
+</plugin>
+```
+
+Some plugins can be configured separately using plugin's fully qualified name. For example:
+
+```xml
+<pluginsConfiguration>
+    <org.jetbrains.dokka.base.DokkaBase>
+        <customStyleSheets>
+            <customStyleSheet><!-- path to custom stylesheet --></customStyleSheet>
+        </customStyleSheets>
+        <customAssets>
+            <customAsset><!-- path to custom asset --></customAsset>
+        </customAssets>
+    </org.jetbrains.dokka.base.DokkaBase>
+</pluginsConfiguration>
+```
+
+## Example project
+
+Please see the [Dokka Maven example project](https://github.com/Kotlin/dokka/tree/master/examples/maven) for an example.