Developers review second round

Author: AlejandraPedroza

docs/dokka.tree

@@ -1,6 +1,6 @@
 <?xml version='1.0' encoding='utf-8'?>
 <!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
-<instance-profile id="dokka" name="dokka" start-page="dokka-gradle-troubleshooting-md.md">
+<instance-profile id="dokka" name="dokka" start-page="dokka-introduction.md">
 	<snippet id="dokka">
 		<toc-element topic="dokka-introduction.md"/>
 		<toc-element topic="dokka-get-started.md"/>
@@ -13,7 +13,6 @@
 		</toc-element>
 		<toc-element toc-title="Output formats">
 			<toc-element topic="dokka-html.md"/>
-			<toc-element topic="dokka-markdown.md"/>
 			<toc-element topic="dokka-javadoc.md"/>
 		</toc-element>
 		<toc-element topic="dokka-plugins.md"/>

docs/topics/dokka-get-started.md

@@ -5,7 +5,7 @@ Below you can find simple instructions to help you get started with Dokka.
 <tabs group="build-script">
 <tab title="Gradle Kotlin DSL" group-key="kotlin">
 
-> This guide applies to Dokka Gradle Plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported. 
+> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported. 
 > If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md).
 >
 {style="note"}
@@ -63,20 +63,19 @@ plugins {
 ```
 
 When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need
-to apply the Gradle plugin within subprojects as well:
+to [share Gradle configuration across subprojects](dokka-gradle.md#multi-project-configuration).
 
-```groovy
-subprojects {
-    apply plugin: 'org.jetbrains.dokka'
-}
-```
+To generate documentation, run the following Gradle task:
 
-To generate documentation, run the following Gradle tasks:
+```Bash
+./gradlew :dokkaGenerate
+```
 
-* `dokkaHtml` for single-project builds
-* `dokkaHtmlMultiModule` for multi-project builds
+This task works for both single and multi-project builds.
+You can use different tasks to generate output in [HTML](dokka-html.md),
+[Javadoc](dokka-javadoc.md) or both [HTML and Javadoc](dokka-gradle.md#configure-documentation-output-format).
 
-By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
+By default, the output directory is set to `build/dokka/html`.
 
 > To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
 >

docs/topics/dokka-introduction.md

@@ -7,7 +7,9 @@ Just like Kotlin itself, Dokka supports mixed-language projects. It understands
 [Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html).
 
 Dokka can generate documentation in multiple formats, including its own modern [HTML format](dokka-html.md),
-multiple flavors of [Markdown](dokka-markdown.md), and Java's [Javadoc HTML](dokka-javadoc.md).
+[GFM](https://github.com/Kotlin/dokka/blob/8e5c63d035ef44a269b8c43430f43f5c8eebfb63/dokka-subprojects/plugin-gfm/README.md) and 
+[Jekyll](https://github.com/Kotlin/dokka/blob/8e5c63d035ef44a269b8c43430f43f5c8eebfb63/dokka-subprojects/plugin-jekyll/README.md) flavors of Markdown, 
+and Java's [Javadoc HTML](dokka-javadoc.md).
 
 Here are some libraries that use Dokka for their API reference documentation:
 

docs/topics/dokka-migration.md

@@ -38,7 +38,7 @@ Ensure that your project meets the minimum version requirements:
 >
 {style="note"}
 
-Update the Dokka version to 2.0.0 in the `plugins {}` block of your project’s `build.gradle.kts` file:
+Update the Dokka version to %dokkaVersion% in the `plugins {}` block of your project’s `build.gradle.kts` file:
 
 ```kotlin
 plugins {
@@ -132,7 +132,7 @@ Configuration in DGP v2:
 The syntax of `build.gradle.kts` files differs from regular `.kt` files (such as those used for custom Gradle plugins) because Gradle's Kotlin DSL uses type-safe accessors.
 
 <tabs group="dokka-configuration">
-<tab title="Gradle configuration file" group-key="gradle">
+<tab title="Gradle configuration" group-key="gradle">
 
 ```kotlin
 // build.gradle.kts
@@ -160,7 +160,7 @@ dokka {
 ```
 
 </tab>
-<tab title="Kotlin file" group-key="kotlin">
+<tab title="Kotlin custom plugin" group-key="kotlin">
 
 ```kotlin
 // CustomPlugin.kt
@@ -266,7 +266,7 @@ Configuration in DGP v2:
 The syntax of `build.gradle.kts` files differs from regular `.kt` files (such as those used for custom Gradle plugins) because Gradle's Kotlin DSL uses type-safe accessors.
 
 <tabs group="dokka-configuration">
-<tab title="Gradle configuration file" group-key="gradle">
+<tab title="Gradle configuration" group-key="gradle">
 
 ```kotlin
 // build.gradle.kts
@@ -283,7 +283,7 @@ dokka {
 ```
 
 </tab>
-<tab title="Kotlin file" group-key="kotlin">
+<tab title="Kotlin custom plugin" group-key="kotlin">
 
 ```kotlin
 // CustomPlugin.kt
@@ -441,7 +441,7 @@ Configuration in DGP v2:
 The syntax of `build.gradle.kts` files differs from regular `.kt` files (such as those used for custom Gradle plugins) because Gradle's Kotlin DSL uses type-safe accessors.
 
 <tabs group="dokka-configuration">
-<tab title="Gradle configuration file" group-key="gradle">
+<tab title="Gradle configuration" group-key="gradle">
 
 ```kotlin
 // build.gradle.kts
@@ -455,7 +455,7 @@ dokka {
 ```
 
 </tab>
-<tab title="Kotlin file" group-key="kotlin">
+<tab title="Kotlin custom plugin" group-key="kotlin">
 
 ```kotlin
 // CustomPlugin.kt
@@ -575,7 +575,7 @@ by creating a convention plugin in the `buildSrc` directory, and then applying t
     }
 
     dependencies {
-        implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0")
+        implementation("org.jetbrains.dokka:dokka-gradle-plugin:%dokkaVersion%")
     }   
     ```
 
@@ -723,7 +723,7 @@ to generate output in HTML, Javadoc or both HTML and Javadoc. For more informati
 > You may find bugs and experience migration issues when using it. Successful integration with tools that accept Javadoc
 > as input is not guaranteed. Use it at your own risk.
 >
-{style="note"}
+{style="warning"}
 
 The default output format for DGP v2 is HTML. However, you can choose to generate the API documentation in HTML, Javadoc, 
 or both formats at the same time:
@@ -789,4 +789,4 @@ DGP v2 now supports Gradle build cache and configuration cache, improving build
 
 * [Explore more DGP v2 project examples](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2). 
 * [Get started with Dokka](dokka-get-started.md).
-* [Learn more about Dokka plugins](dokka-plugins.md).
+* [Learn more about Dokka plugins](dokka-plugins.md).

docs/topics/dokka-module-and-package-docs.md

@@ -1,4 +1,4 @@
-[//]: # (title: Subproject documentation)
+[//]: # (title: Module documentation)
 
 Documentation for a subproject as a whole, as well as packages in that subproject, can be provided as separate Markdown files.
 

docs/topics/dokka-plugins.md

@@ -1,6 +1,6 @@
 [//]: # (title: Dokka plugins)
 
-> This guide applies to Dokka Gradle Plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported.
+> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported.
 > If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md).
 >
 {style="note"}
@@ -56,25 +56,18 @@ dependencies {
 </tab>
 <tab title="Groovy" group-key="groovy">
 
-The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply Dokka plugins universally or
-for a specific output format only.
-
 ```groovy
-dependencies {
-    // Is applied universally
-    dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%'
-
-    // Is applied for the single-module dokkaHtml task only
-    dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%'
+plugins {
+    id 'org.jetbrains.dokka' version '%dokkaVersion%'
+}
 
-    // Is applied for HTML format in multi-project builds
-    dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%'
+dependencies {
+    dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin'
 }
 ```
 
 > When documenting [multi-project](dokka-gradle.md#multi-project-configuration) builds, 
-> you need to apply Dokka plugins within
-> subprojects as well as in their parent project.
+> you need to [share Dokka configuration across subprojects](dokka-gradle.md#multi-project-configuration).
 >
 {style="note"}
 
@@ -164,20 +157,14 @@ Custom plugins enable additional processing or modifications to the documentatio
 <tab title="Groovy" group-key="groovy">
 
 ```groovy
-import org.jetbrains.dokka.gradle.DokkaTask
-
-tasks.withType(DokkaTask.class) {
-    String dokkaBaseConfiguration = """
-    {
-      "customAssets": ["${file("assets/my-image.png")}"],
-      "customStyleSheets": ["${file("assets/my-styles.css")}"],
-      "footerMessage": "(c) 2022 MyOrg"
+dokka {
+    pluginsConfiguration {
+        html {
+            customAssets.from("logo.png")
+            customStyleSheets.from("styles.css")
+            footerMessage.set("(c) Your Company")
+        }
     }
-    """
-    pluginsMapConfiguration.set(
-            // fully qualified plugin name to json configuration
-            ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
-    )
 }
 ```
 
@@ -251,6 +238,8 @@ Here are some notable Dokka plugins that you might find useful:
 | [MermaidJS HTML plugin](https://github.com/glureau/dokka-mermaid)                                                                  | Renders [MermaidJS](https://mermaid-js.github.io/mermaid/#/) diagrams and visualizations found in KDocs      |
 | [Mathjax HTML plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-mathjax)                        | Pretty prints mathematics found in KDocs                                                                     |
 | [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-kotlin-as-java)               | Renders Kotlin signatures as seen from Java's perspective                                                    |
+| [GFM plugin](https://github.com/Kotlin/dokka/tree/master/dokka-subprojects/plugin-gfm)                                                                                                                     | Adds the ability to generate documentation in GitHub Flavoured Markdown format                               |
+| [Jekyll plugin](https://github.com/Kotlin/dokka/tree/master/dokka-subprojects/plugin-jekyll)                                                                                                                                                                                                           | Adds the ability to generate documentation in Jekyll Flavoured Markdown format                               |
 
 If you are a Dokka plugin author and would like to add your plugin to this list, get in touch with maintainers
 via [Slack](dokka-introduction.md#community) or [GitHub](https://github.com/Kotlin/dokka/).

docs/topics/formats/dokka-html.md

@@ -1,6 +1,6 @@
 [//]: # (title: HTML)
 
-> This guide applies to Dokka Gradle Plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported.
+> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported.
 > If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md).
 >
 {style="note"}
@@ -67,23 +67,19 @@ dokka {
 <tab title="Groovy" group-key="groovy">
 
 ```groovy
-import org.jetbrains.dokka.gradle.DokkaTask
+// build.gradle
 
-tasks.withType(DokkaTask.class) {
-    String dokkaBaseConfiguration = """
-    {
-      "customAssets": ["${file("assets/my-image.png")}"],
-      "customStyleSheets": ["${file("assets/my-styles.css")}"],
-      "footerMessage": "(c) 2022 MyOrg"
-      "separateInheritedMembers": false,
-      "templatesDir": "${file("dokka/templates")}",
-      "mergeImplicitExpectActualDeclarations": false
+dokka {
+    pluginsConfiguration {
+        html {
+            customAssets.from("logo.png")
+            customStyleSheets.from("styles.css")
+            footerMessage.set("(c) Your Company")
+            separateInheritedMembers.set(false)
+            templatesDir.set(file("dokka/templates"))
+            mergeImplicitExpectActualDeclarations.set(false)
+        }
     }
-    """
-    pluginsMapConfiguration.set(
-            // fully qualified plugin name to json configuration
-            ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
-    )
 }
 ```
 

docs/topics/formats/dokka-javadoc.md

@@ -1,7 +1,7 @@
 [//]: # (title: Javadoc)
 <primary-label ref="alpha"/>
 
-> This guide applies to Dokka Gradle Plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported.
+> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported.
 > If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md).
 >
 {style="note"}