Revise README documentation for examples and plugins (#2736)

60 files changed, 3633 insertions, 20 deletions

diff --git a/examples/gradle/dokka-versioning-multimodule-example/README.md b/examples/gradle/dokka-versioning-multimodule-example/README.md
new file mode 100644
index 00000000..dd012003
--- /dev/null
+++ b/examples/gradle/dokka-versioning-multimodule-example/README.md
@@ -0,0 +1,25 @@
+# Dokka Versioning MultiModule example
+
+This example demonstrates configuration of Dokka's [versioning plugin](../../../plugins/versioning), which
+allows readers to navigate through different versions of your API reference documentation.
+
+The example contains some code that exists only in the current documentation version `1.0`. You will not see
+this code in the previous version `0.9`, which is located in the [previousDocVersions](previousDocVersions) directory.
+
+___
+
+You can see up-to-date documentation generated for this example on
+[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-versioning-multimodule-example/htmlMultiModule/index.html).
+
+![screenshot demonstration of output](demo.png)
+
+### Running
+
+Run `dokkaHtmlMultiModule` task to generate documentation for this example:
+
+```bash
+./gradlew dokkaHtmlMultiModule
+```
+
+It will generate complete documentation for the root project and its subprojects, with the version navigation
+dropdown menu.
diff --git a/examples/gradle/dokka-versioning-multimodule-example/build.gradle.kts b/examples/gradle/dokka-versioning-multimodule-example/build.gradle.kts
index 96a7280c..e14e7394 100644
--- a/examples/gradle/dokka-versioning-multimodule-example/build.gradle.kts
+++ b/examples/gradle/dokka-versioning-multimodule-example/build.gradle.kts
@@ -3,7 +3,7 @@ plugins {
     id("org.jetbrains.dokka") version ("1.7.20") apply false
 }
 
-// The versioning plugin should be applied in all submodules
+// The versioning plugin must be applied in all submodules
 subprojects {
     repositories {
         mavenCentral()
diff --git a/examples/gradle/dokka-versioning-multimodule-example/demo.png b/examples/gradle/dokka-versioning-multimodule-example/demo.png
new file mode 100644
index 00000000..9ac1d382
--- /dev/null
+++ b/examples/gradle/dokka-versioning-multimodule-example/demo.png
diff --git a/examples/gradle/dokka-versioning-multimodule-example/parentProject/build.gradle.kts b/examples/gradle/dokka-versioning-multimodule-example/parentProject/build.gradle.kts
index dc909192..8387d9c8 100644
--- a/examples/gradle/dokka-versioning-multimodule-example/parentProject/build.gradle.kts
+++ b/examples/gradle/dokka-versioning-multimodule-example/parentProject/build.gradle.kts
@@ -1,25 +1,31 @@
 import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
+import org.jetbrains.dokka.versioning.VersioningPlugin
+import org.jetbrains.dokka.versioning.VersioningConfiguration
+
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.dokka:versioning-plugin:1.7.20")
+    }
+
+    repositories {
+        mavenCentral()
+    }
+}
 
 dependencies {
     implementation(kotlin("stdlib"))
 }
 
-val olderVersionsFolder = "olderVersions"
-
-// The previously documentations should be generated with the versioning plugin
-val generatePreviouslyDocTask by tasks.register<DokkaMultiModuleTask>("dokkaPreviouslyDocumentation") {
-    dependencies {
-        dokkaPlugin("org.jetbrains.dokka:all-modules-page-plugin:1.7.20")
-        dokkaPlugin("org.jetbrains.dokka:versioning-plugin:1.7.20")
-    }
-    val configuredVersion = "0.9"
-    outputDirectory.set(file(projectDir.resolve(olderVersionsFolder).resolve(configuredVersion)))
-    pluginsMapConfiguration.set(mapOf("org.jetbrains.dokka.versioning.VersioningPlugin" to """{ "version": "$configuredVersion" }"""))
-    addChildTasks(listOf(project("childProjectA"), project("childProjectB")), "dokkaHtmlPartial")
-}
+val currentVersion = "1.0"
+val previousVersionsDirectory = project.rootProject.projectDir.resolve("previousDocVersions").invariantSeparatorsPath
 
+// Main configuration for the versioning plugin. It will generate documentation for
+// the current version of the application, and look for previous versions of docs
+// in the directory defined in previousVersionsDirectory, allowing it to create
+// the version navigation dropdown menu.
 tasks.dokkaHtmlMultiModule {
-    dependsOn(generatePreviouslyDocTask)
-    val configuredVersion = "1.0"
-    pluginsMapConfiguration.set(mapOf("org.jetbrains.dokka.versioning.VersioningPlugin" to """{ "version": "$configuredVersion", "olderVersionsDir": "${projectDir.resolve(olderVersionsFolder).invariantSeparatorsPath}" }"""))
+    pluginConfiguration<VersioningPlugin, VersioningConfiguration> {
+        version = currentVersion
+        olderVersionsDir = file(previousVersionsDirectory)
+    }
 }
diff --git a/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt b/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt
index 533b305c..e0f9e86a 100644
--- a/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt
+++ b/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/src/main/kotlin/demo/ChildProjectAClass.kt
@@ -3,6 +3,16 @@
 package demo
 
 /**
- * Class defined in child project a
+ * Class defined in child project A
+ *
+ * @since 0.9
  */
-class ChildProjectAClass
+class ChildProjectAClass {
+
+    /**
+     * Function that extends [ChildProjectAClass]
+     *
+     * @since 1.0
+     */
+    fun extend() {}
+}
diff --git a/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/src/main/kotlin/demo/FancyAPI.kt b/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/src/main/kotlin/demo/FancyAPI.kt
new file mode 100644
index 00000000..e691be03
--- /dev/null
+++ b/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/src/main/kotlin/demo/FancyAPI.kt
@@ -0,0 +1,10 @@
+package demo
+
+/**
+ * New shiny fancy API
+ *
+ * @since 1.0
+ */
+class FancyAPI {
+    fun doSomething() {}
+}
diff --git a/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt b/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt
index 6bfd22eb..6978a176 100644
--- a/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt
+++ b/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass.kt
@@ -3,6 +3,8 @@
 package demo
 
 /**
- * Class defined in child module b
+ * Class defined in child module B
+ *
+ * @since 0.9
  */
 class ChildProjectBClass
diff --git a/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectB/src/main/kotlin/demo/Functions.kt b/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectB/src/main/kotlin/demo/Functions.kt
new file mode 100644
index 00000000..35a9275b
--- /dev/null
+++ b/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectB/src/main/kotlin/demo/Functions.kt
@@ -0,0 +1,8 @@
+package demo
+
+/**
+ * New super function that does everything
+ *
+ * @since 1.0
+ */
+fun superFunction42() {}
diff --git a/examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/-child-project-a-class/-child-project-a-class.html b/examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/-child-project-a-class/-child-project-a-class.html
new file mode 100644
index 00000000..d29125e4
--- /dev/null
+++ b/examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/-child-project-a-class/-child-project-a-class.html
@@ -0,0 +1,64 @@
+<!doctype html>
+<html>
+<head>
+    <meta name="viewport" content="width=device-width, initial-scale=1" charset="UTF-8">
+    <title>ChildProjectAClass</title>
+<link href="../../../images/logo-icon.svg" rel="icon" type="image/svg"><script>var pathToRoot = "../../../";</script>    <script>const storage = localStorage.getItem("dokka-dark-mode")
+    if (storage == null) {
+        const osDarkSchemePreferred = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
+        if (osDarkSchemePreferred === true) {
+            document.getElementsByTagName("html")[0].classList.add("theme-dark")
+        }
+    } else {
+        const savedDarkMode = JSON.parse(storage)
+        if(savedDarkMode === true) {
+            document.getElementsByTagName("html")[0].classList.add("theme-dark")
+        }
+    }
+    </script>
+<script type="text/javascript" src="../../../scripts/sourceset_dependencies.js" async></script>
+<link href="../../../styles/style.css" rel="Stylesheet">
+<link href="../../../styles/jetbrains-mono.css" rel="Stylesheet">
+<link href="../../../styles/main.css" rel="Stylesheet">
+<link href="../../../styles/prism.css" rel="Stylesheet">
+<link href="../../../styles/logo-styles.css" rel="Stylesheet">
+<script type="text/javascript" src="../../../scripts/clipboard.js" async></script>
+<script type="text/javascript" src="../../../scripts/navigation-loader.js" async></script>
+<script type="text/javascript" src="../../../scripts/platform-content-handler.js" async></script>
+<script type="text/javascript" src="../../../scripts/main.js" defer></script>
+<script type="text/javascript" src="../../../scripts/prism.js" async></script>
+<script type="text/javascript" src="../../../scripts/symbol-parameters-wrapper_deferred.js" defer></script>
+<link href="../../../styles/multimodule.css" rel="Stylesheet"></head>
+<body>
+<div class="navigation-wrapper" id="navigation-wrapper">
+    <div id="leftToggler"><span class="icon-toggler"></span></div>
+    <div class="library-name">
+<a href="../../../index.html">
+<span>parentProject</span>            </a>    </div>
+    <div>
+<dokka-template-command data="{&quot;@class&quot;:&quot;org.jetbrains.dokka.base.templating.ReplaceVersionsCommand&quot;,&quot;location&quot;:&quot;demo/-child-project-a-class/-child-project-a-class.html&quot;}">0.9</dokka-template-command>    </div>
+    <div class="pull-right d-flex">
+        <button id="theme-toggle-button"><span id="theme-toggle"></span></button>
+        <div id="searchBar"></div>
+    </div>
+</div>
+<div id="container">
+    <div id="leftColumn">
+        <div id="sideMenu"></div>
+    </div>
+    <div id="main">
+<div class="main-content" id="content" pageids="childProjectA::demo/ChildProjectAClass/ChildProjectAClass/#/PointingToDeclaration//-638285599">
+  <div class="breadcrumbs"><a href="../../index.html">childProjectA</a><span class="delimiter">/</span><a href="../index.html">demo</a><span class="delimiter">/</span><a href="index.html">ChildProjectAClass</a><span class="delimiter">/</span><span class="current">ChildProjectAClass</span></div>
+  <div class="cover ">
+    <h1 class="cover"><span>Child</span><wbr><span>Project</span><wbr><span><span>AClass</span></span></h1>
+  </div>
+  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":parentProject:childProjectA:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword"></span><span class="token keyword">fun </span><a href="-child-project-a-class.html"><span class="token function">ChildProjectAClass</span></a><span class="token punctuation">(</span><span class="token punctuation">)</span></div></div></div>
+</div>
+      <div class="footer">
+        <span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2022 Copyright</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span>
+      </div>
+    </div>
+</div>
+
+</body></html>
+
diff --git a/examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/-child-project-a-class/index.html b/examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/-child-project-a-class/index.html
new file mode 100644
index 00000000..be7432a6
--- /dev/null
+++ b/examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/-child-project-a-class/index.html
@@ -0,0 +1,86 @@
+<!doctype html>
+<html>
+<head>
+    <meta name="viewport" content="width=device-width, initial-scale=1" charset="UTF-8">
+    <title>ChildProjectAClass</title>
+<link href="../../../images/logo-icon.svg" rel="icon" type="image/svg"><script>var pathToRoot = "../../../";</script>    <script>const storage = localStorage.getItem("dokka-dark-mode")
+    if (storage == null) {
+        const osDarkSchemePreferred = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
+        if (osDarkSchemePreferred === true) {
+            document.getElementsByTagName("html")[0].classList.add("theme-dark")
+        }
+    } else {
+        const savedDarkMode = JSON.parse(storage)
+        if(savedDarkMode === true) {
+            document.getElementsByTagName("html")[0].classList.add("theme-dark")
+        }
+    }
+    </script>
+<script type="text/javascript" src="../../../scripts/sourceset_dependencies.js" async></script>
+<link href="../../../styles/style.css" rel="Stylesheet">
+<link href="../../../styles/jetbrains-mono.css" rel="Stylesheet">
+<link href="../../../styles/main.css" rel="Stylesheet">
+<link href="../../../styles/prism.css" rel="Stylesheet">
+<link href="../../../styles/logo-styles.css" rel="Stylesheet">
+<script type="text/javascript" src="../../../scripts/clipboard.js" async></script>
+<script type="text/javascript" src="../../../scripts/navigation-loader.js" async></script>
+<script type="text/javascript" src="../../../scripts/platform-content-handler.js" async></script>
+<script type="text/javascript" src="../../../scripts/main.js" defer></script>
+<script type="text/javascript" src="../../../scripts/prism.js" async></script>
+<script type="text/javascript" src="../../../scripts/symbol-parameters-wrapper_deferred.js" defer></script>
+<link href="../../../styles/multimodule.css" rel="Stylesheet"></head>
+<body>
+<div class="navigation-wrapper" id="navigation-wrapper">
+    <div id="leftToggler"><span class="icon-toggler"></span></div>
+    <div class="library-name">
+<a href="../../../index.html">
+<span>parentPr