Developer's reviews

AlejandraPedroza · AlejandraPedroza · commit 729484ac6d36 · 2025-11-19T16:48:24.000-06:00
diff --git a/docs/topics/dokka-get-started.md b/docs/topics/dokka-get-started.md
@@ -5,6 +5,11 @@ 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. 
+> If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md).
+>
+{style="note"}
+
 **Apply the Gradle Dokka plugin** 
 
 Apply the Dokka Gradle plugin (DGP) in the root build script of your project:
@@ -15,16 +20,16 @@ plugins {
 }
 ```
 
-**Document multi-module projects**
+**Document multi-project builds**
 
-When documenting [multi-module projects (multi-project builds)](https://docs.gradle.org/current/userguide/multi_project_builds.html),
-you don't need to apply the plugin to every module or subproject you want to document. Instead, share Dokka configuration across modules 
+When documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html),
+you need to apply the plugin to every subproject you want to document. Share Dokka configuration across subprojects 
 by using one of the following approaches:
 
 * Convention plugin
-* Direct configuration in each module if you’re not using convention plugins
+* Direct configuration in each subproject if you’re not using convention plugins
 
-For more information about sharing Dokka configuration in multi-module projects, 
+For more information about sharing Dokka configuration in multi-project builds, 
 see [Multi-project configuration](dokka-gradle.md#multi-project-configuration).
 
 **Generate documentation**
@@ -35,13 +40,13 @@ To generate documentation, run the following Gradle task:
 ./gradlew :dokkaGenerate
 ```
 
-This task works for both single and multi-module projects. 
+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).
 
 **Set output directory** 
 
-By default, the output directory is set to `/build/dokka/html` for both multi-module and single-module projects, 
+By default, the output directory is set to `/build/dokka/html` for both multi-project and single-project builds, 
 but you can [configure it](dokka-gradle.md#general-configuration).
 
 To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
diff --git a/docs/topics/dokka-migration.md b/docs/topics/dokka-migration.md
@@ -43,7 +43,7 @@ Update the Dokka version to 2.0.0 in the `plugins {}` block of your project’s
 ```kotlin
 plugins {
     kotlin("jvm") version "2.1.10"
-    id("org.jetbrains.dokka") version "2.0.0"
+    id("org.jetbrains.dokka") version "%dokkaVersion%"
 }
 ```
 
@@ -525,15 +525,15 @@ For an example of the DGP v2 configuration, see the
 DGP v2 allows you to extend its functionality by [configuring custom plugins](https://github.com/Kotlin/dokka/blob/ae3840edb4e4afd7b3e3768a5fddfe8ec0e08f31/examples/gradle-v2/custom-dokka-plugin-example/demo-library/build.gradle.kts).
 Custom plugins enable additional processing or modifications to the documentation generation process.
 
-### Share Dokka configuration across modules
+### Share Dokka configuration across subprojects
 
-DPG v2 moves away from using `subprojects {}` or `allprojects {}` to share configuration across modules. In future Gradle versions, 
+DPG v2 moves away from using `subprojects {}` or `allprojects {}` to share configuration across subprojects. In future Gradle versions, 
 using these approaches will [lead to errors](https://docs.gradle.org/current/userguide/isolated_projects.html).
 
 Follow the steps below to properly share Dokka configuration in multi-module projects [with existing convention plugins](#multi-module-projects-with-convention-plugins)
 or [without convention plugins](#multi-module-projects-without-convention-plugins).
 
-After sharing the Dokka configuration, you can aggregate the documentation from multiple modules into a single output. For more information, see
+After sharing the Dokka configuration, you can aggregate the documentation from multiple subprojects into a single output. For more information, see
 [Update documentation aggregation in multi-module projects](#update-documentation-aggregation-in-multi-module-projects).
 
 > For a multi-module project example, see the [Dokka GitHub repository](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/multimodule-example).
@@ -542,12 +542,12 @@ After sharing the Dokka configuration, you can aggregate the documentation from
 
 #### Multi-module projects without convention plugins
 
-If your project doesn't use convention plugins, you can still share Dokka configurations by directly configuring each module. 
-This involves manually setting up the shared configuration in each module's `build.gradle.kts` file. While this approach is less centralized, 
+If your project doesn't use convention plugins, you can still share Dokka configurations by directly configuring each subproject. 
+This involves manually setting up the shared configuration in each subproject's `build.gradle.kts` file. While this approach is less centralized, 
 it avoids the need for additional setups like convention plugins.
 
 Otherwise, if your project uses convention plugins, you can also share the Dokka configuration in multi-module projects 
-by creating a convention plugin in the `buildSrc` directory, and then applying the plugin to your modules (subprojects).
+by creating a convention plugin in the `buildSrc` directory, and then applying the plugin to your subprojects.
 
 ##### Set up the buildSrc directory
 
@@ -599,9 +599,9 @@ After setting up the `buildSrc` directory:
    You need to add the shared Dokka [configuration](#adjust-configuration-options) common to all subprojects within the `dokka {}` block.
    Also, you don't need to specify a Dokka version. The version is already set in the `buildSrc/build.gradle.kts` file.
 
-##### Apply the convention plugin to your modules
+##### Apply the convention plugin to your subprojects
 
-Apply the Dokka convention plugin across your modules (subprojects) by adding it to each subproject's `build.gradle.kts` file:
+Apply the Dokka convention plugin across your subprojects by adding it to each subproject's `build.gradle.kts` file:
 
 ```kotlin
 plugins {
@@ -614,13 +614,13 @@ plugins {
 If you already have convention plugins, create a dedicated Dokka convention plugin following [Gradle's documentation](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:convention_plugins).
 
 Then, follow the steps to [set up the Dokka convention plugin](#set-up-the-dokka-convention-plugin) and 
-[apply it across your modules](#apply-the-convention-plugin-to-your-modules).
+[apply it across your subprojects](#apply-the-convention-plugin-to-your-subprojects).
 
 ### Update documentation aggregation in multi-module projects
 
-Dokka can aggregate the documentation from multiple modules (subprojects) into a single output or publication.
+Dokka can aggregate the documentation from multiple subprojects into a single output or publication.
 
-As [explained](#apply-the-convention-plugin-to-your-modules), apply the Dokka plugin to all documentable subprojects before aggregating the documentation.
+As [explained](#apply-the-convention-plugin-to-your-subprojects), apply the Dokka plugin to all documentable subprojects before aggregating the documentation.
 
 Aggregation in DGP v2 uses the `dependencies {}` block instead of tasks and can be added in any `build.gradle.kts` file. 
 
@@ -646,7 +646,7 @@ dependencies {
 
 ### Change directory of aggregated documentation
 
-When DGP aggregates modules, each subproject has its own subdirectory within the aggregated documentation.
+When DGP aggregates subprojects, each subproject has its own subdirectory within the aggregated documentation.
 
 In DGP v2, the aggregation mechanism has been updated to better align with Gradle conventions. 
 DGP v2 now preserves the full subproject directory to prevent conflicts when aggregating 
@@ -676,7 +676,7 @@ may become outdated, potentially causing `404` errors.
 
 #### Revert to the DGP v1 directory behavior
 
-If your project depends on the directory structure used in DGP v1, you can revert this behavior by manually specifying the module directory.
+If your project depends on the directory structure used in DGP v1, you can revert this behavior by manually specifying the subproject directory.
 Add the following configuration to the `build.gradle.kts` file of each subproject:
 
 ```kotlin
@@ -687,7 +687,7 @@ plugins {
 }
 
 dokka {
-    // Overrides the module directory to match the V1 structure
+    // Overrides the subproject directory to match the V1 structure
     modulePath.set("maths")
 }
 ```
@@ -733,10 +733,10 @@ or both formats at the same time:
    ```kotlin
    plugins {
        // Generates HTML documentation
-       id("org.jetbrains.dokka") version "2.0.0"
+       id("org.jetbrains.dokka") version "%dokkaVersion%"
 
        // Generates Javadoc documentation
-       id("org.jetbrains.dokka-javadoc") version "2.0.0"
+       id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%"
 
        // Keeping both plugin IDs generates both formats
    }
diff --git a/docs/topics/dokka-module-and-package-docs.md b/docs/topics/dokka-module-and-package-docs.md
@@ -1,15 +1,15 @@
-[//]: # (title: Module documentation)
+[//]: # (title: Subproject documentation)
 
-Documentation for a module as a whole, as well as packages in that module, can be provided as separate Markdown files.
+Documentation for a subproject as a whole, as well as packages in that subproject, can be provided as separate Markdown files.
 
 ## File format
 
-Inside the Markdown file, the documentation for the module as a whole and for individual packages is introduced by the corresponding
-first-level headings. The text of the heading **must** be **Module `<module name>`** for a module, and **Package `<package qualified name>`**
+Inside the Markdown file, the documentation for the subproject as a whole and for individual packages is introduced by the corresponding
+first-level headings. The text of the heading **must** be **Module `<module name>`** for a subproject, and **Package `<package qualified name>`**
 for a package. 
 
-The file doesn't have to contain both module and package documentation. You can have files that contain only package or 
-module documentation. You can even have a Markdown file per module or package.
+The file doesn't have to contain both subproject and package documentation. You can have files that contain only package or
+subproject documentation. You can even have a Markdown file per subproject or package.
 
 Using [Markdown syntax](https://www.markdownguide.org/basic-syntax/), you can add:
 * Headings up to level 6
@@ -19,12 +19,12 @@ Using [Markdown syntax](https://www.markdownguide.org/basic-syntax/), you can ad
 * Code blocks
 * Blockquotes
 
-Here's an example file containing both module and package documentation:
+Here's an example file containing both subproject and package documentation:
 
 ```text
 # Module kotlin-demo
 
-This content appears under your module name.
+This content appears under your subproject name.
 
 # Package org.jetbrains.kotlin.demo
 
diff --git a/docs/topics/dokka-plugins.md b/docs/topics/dokka-plugins.md
@@ -1,5 +1,10 @@
 [//]: # (title: Dokka plugins)
 
+> 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"}
+
 Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community
 to implement plugins for missing or very specific features that are not provided out of the box.
 
@@ -30,24 +35,21 @@ to your project:
 <tabs group="build-script">
 <tab title="Kotlin" group-key="kotlin">
 
-The way to apply Dokka plugins is unified under the `dokka {}` DSL:
+The way to apply Dokka plugins is:
 
 ```kotlin
 plugins {
-    id("org.jetbrains.dokka") version "2.0.0"
+    id("org.jetbrains.dokka") version "%dokkaVersion%"
 }
 
-dokka {
-    dependencies {
-        dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:2.0.0")
-    }
-
+dependencies {
+    dokkaPlugin("org.jetbrains.dokka:mathjax-plugin")
 }
 ```
 
 > * Built-in plugins (like HTML and Javadoc) are always applied automatically. You only configure them and do not need dependencies for them.
 >
-> * When documenting multi-module projects (multi-project builds), you need to [share Dokka configuration and plugins across modules](dokka-gradle.md#multi-project-configuration).
+> * When documenting multi-module projects (multi-project builds), you need to [share Dokka configuration and plugins across subprojects](dokka-gradle.md#multi-project-configuration).
 > 
 {style="note"}
 
@@ -138,7 +140,7 @@ custom style sheets (`customStyleSheets` option), and a modified footer message
 <tabs group="build-script">
 <tab title="Kotlin" group-key="kotlin">
 
-To configure Dokka plugins in a type-safe way, use the `pluginsConfiguration{}` block:
+To configure Dokka plugins in a type-safe way, use the `dokka.pluginsConfiguration {}` block:
 
 ```kotlin
 dokka {
@@ -155,7 +157,7 @@ For an example of Dokka plugins configuration, see the
 
 Dokka allows you 
 to extend its functionality 
-by [configuring custom plugins](https://github.com/Kotlin/dokka/blob/ae3840edb4e4afd7b3e3768a5fddfe8ec0e08f31/examples/gradle-v2/custom-dokka-plugin-example/demo-library/build.gradle.kts).
+by [configuring custom plugins](https://github.com/Kotlin/dokka/blob/v2.1.0/examples/gradle-v2/custom-dokka-plugin-example/demo-library/build.gradle.kts).
 Custom plugins enable additional processing or modifications to the documentation generation process.
 
 </tab>
diff --git a/docs/topics/formats/dokka-html.md b/docs/topics/formats/dokka-html.md
@@ -1,17 +1,34 @@
 [//]: # (title: HTML)
 
-HTML is Dokka's default and recommended output format. 
-You can see an example of the output by browsing documentation
-for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/).
+> 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"}
+
+HTML is Dokka's default and recommended output format.
+It provides support for Kotlin Multiplatform, Android, and Java projects. 
+Additionally, you can use the HTML format to document both single and multi-project builds.
+
+For examples of the HTML output format, check the following docs:
+* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/)
+* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
+* [Hexagon](https://hexagontk.com/stable/api/)
+* [Ktor](https://api.ktor.io/)
+* [OkHttp](https://square.github.io/okhttp/5.x/okhttp/okhttp3/)
+* [Gradle](https://docs.gradle.org/current/kotlin-dsl/index.html)
 
 ## Generate HTML documentation
 
 HTML as an output format is supported by all runners. To generate HTML documentation, follow these steps depending on 
 your build tool or runner:
 
 * For [Gradle](dokka-gradle.md#generate-documentation), run the following tasks: 
-  * `dokkaGeneratePublicationHtml` to generate documentation only in HTML format. 
   * `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format).
+      This is the recommended task for most users. When using this task in IntelliJ IDEA, it logs a clickable link to the output.
+  * `dokkaGeneratePublicationHtml` to generate documentation only in HTML format. This task exposes the output directory 
+    as an `@OutputDirectory`. Use this task when you need to consume the generated files in other Gradle tasks, such 
+    as uploading them to a server, moving them into a GitHub Pages directory, or packaging them into a `javadoc.jar`. 
+    This task is intentionally not shown in Gradle task groups because it is not meant for everyday use.
 * For [Maven](dokka-maven.md#generate-documentation), run the `dokka:dokka` goal.
 * For [CLI runner](dokka-cli.md#generate-documentation), run with HTML dependencies set.
 
@@ -206,7 +223,7 @@ You can modify text in the footer by using the `footerMessage` [configuration op
 Dokka provides the ability to modify [FreeMarker](https://freemarker.apache.org/) templates used for generating 
 documentation pages.
 
-You can change the header completely, add your own banners/menus/search, load analytics, change body styling and so on.
+You can change the header completely, add your own banners/menus/search, load analytics, change body styling, and so on.
 
 Dokka uses the following templates:
 
@@ -255,4 +272,4 @@ You can also use the following Dokka-defined [directives](https://freemarker.apa
 |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `<@content/>`   | The main page content.                                                                                                                                                                                                |
 | `<@resources/>` | Resources such as scripts and stylesheets.                                                                                                                                                                            |
-| `<@version/>`   | The module version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-versioning) is applied, it is replaced with a version navigator. |
+| `<@version/>`   | The subproject version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-versioning) is applied, it is replaced with a version navigator. |
diff --git a/docs/topics/formats/dokka-javadoc.md b/docs/topics/formats/dokka-javadoc.md
@@ -1,6 +1,11 @@
 [//]: # (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.
+> If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md).
+>
+{style="note"}
+
 Dokka's Javadoc output format is a lookalike of Java's
 [Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). 
 
@@ -19,12 +24,9 @@ and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tre
 
 ## Generate Javadoc documentation
 
-> These instructions reflect Dokka Gradle plugin v1 configuration and tasks. Starting from Dokka 2.0.0, [the Gradle tasks to generate documentation changed](dokka-migration.md#select-documentation-output-format).
-> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md).
->
-> The Javadoc format does not support multiplatform projects.
+> The Javadoc format does not support multi-project builds or Kotlin Multiplatform projects.
 >
-{style="warning"}
+{style="tip"}
 
 
 <tabs group="build-script">
@@ -35,13 +37,14 @@ You need to apply the corresponding plugin id in the `plugins {}` block of your
 
 ```kotlin
 plugins {
-    id("org.jetbrains.dokka-javadoc") version "2.0.0"
+    id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%"
 }
 ```
 
 Once you applied the plugin, you can run the following tasks:
-* `dokkaGeneratePublicationJavadoc` to generate documentation only in Javadoc format.
+
 * `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format).
+* `dokkaGeneratePublicationJavadoc` to generate documentation only in Javadoc format.
 
 The `javadoc.jar` file can be generated separately. For more information, see [Building `javadoc.jar`](dokka-gradle.md#build-javadoc-jar).
 
diff --git a/docs/topics/formats/dokka-markdown.md b/docs/topics/formats/dokka-markdown.md
diff --git a/docs/topics/runners/dokka-gradle.md b/docs/topics/runners/dokka-gradle.md
