From 889997925103ba72b26e8970217b57ca511b0460 Mon Sep 17 00:00:00 2001
From: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>
Date: Wed, 2 Oct 2024 15:50:54 +0200
Subject: [PATCH 01/12] Update and add KDoc for DGPv2

---
 .../src/main/kotlin/DokkaBasePlugin.kt        |  3 -
 .../src/main/kotlin/DokkaExtension.kt         | 65 ++++++++-------
 .../main/kotlin/adapters/AndroidAdapter.kt    |  6 ++
 .../src/main/kotlin/adapters/JavaAdapter.kt   |  3 +-
 .../src/main/kotlin/adapters/KotlinAdapter.kt |  3 +-
 .../kotlin/dependencies/DokkaAttribute.kt     | 17 ++++
 .../dependencies/FormatDependenciesManager.kt | 24 +++++-
 .../ModuleComponentDependencies.kt            |  8 +-
 .../DokkaExternalDocumentationLinkSpec.kt     | 12 ++-
 .../DokkaGeneratorParametersSpec.kt           | 40 +++++----
 .../parameters/DokkaModuleDescriptionKxs.kt   |  2 +-
 .../engine/parameters/DokkaSourceLinkSpec.kt  | 24 ++++--
 .../engine/parameters/DokkaSourceSetSpec.kt   | 12 +--
 .../HasConfigurableVisibilityModifiers.kt     |  3 +
 .../engine/parameters/SourceSetIdSpec.kt      | 14 ++--
 .../builders/DokkaParametersBuilder.kt        |  2 +-
 .../builders/DokkaSourceSetBuilder.kt         |  2 -
 .../main/kotlin/formats/DokkaPublication.kt   | 81 ++++++++++++++++++-
 .../main/kotlin/internal/DokkaInternalApi.kt  |  6 +-
 .../src/main/kotlin/internal/HasFormatName.kt |  3 +
 .../main/kotlin/tasks/DokkaGenerateTask.kt    |  5 ++
 .../tasks/LogHtmlPublicationLinkTask.kt       | 42 +++++-----
 .../src/main/kotlin/tasks/TaskNames.kt        |  3 +
 23 files changed, 274 insertions(+), 106 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt
index 24cf415ddb..1b60aacc52 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt
@@ -102,9 +102,6 @@ constructor(
             sourceSetScopeDefault.convention(project.path)
             dokkaPublicationDirectory.convention(layout.buildDirectory.dir("dokka"))
             dokkaModuleDirectory.convention(layout.buildDirectory.dir("dokka-module"))
-//            @Suppress("DEPRECATION")
-//            dokkaConfigurationsDirectory.convention(layout.buildDirectory.dir("dokka-config"))
-
             dokkaEngineVersion.convention(DokkaConstants.DOKKA_VERSION)
         }
 
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index 742c2323ad..378e66b220 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -45,8 +45,29 @@ constructor(
     /** Default Dokka Gradle Plugin cache directory */
     abstract val dokkaCacheDirectory: DirectoryProperty
 
+    /**
+     * The display name used to refer to the module.
+     * It is used for the table of contents, navigation, logging, etc.
+     *
+     * Default: the current project name.
+     */
     abstract val moduleName: Property<String>
+
+    /**
+     * The displayed module version.
+     *
+     * Default: the version of the current project.
+     */
     abstract val moduleVersion: Property<String>
+
+    /**
+     * A distinct relative path for the Dokka Module produced by the current project.
+     *
+     * Used in Dokka Publications to ensure the files produced by every Dokka Modules
+     * are in their own separate directories.
+     *
+     * Default: the current project's path ([org.gradle.api.Project.getPath]) as a file path.
+     */
     abstract val modulePath: Property<String>
 
     /**
@@ -83,32 +104,9 @@ constructor(
         )
 
     /**
-     * Dokka Source Sets describe the source code that should be included in a Dokka Publication.
+     * Dokka Source Sets describe the source code that should be included in the generated output.
      *
      * Dokka will not generate documentation unless there is at least there is at least one Dokka Source Set.
-     *
-     *  TODO make sure dokkaSourceSets doc is up to date...
-     *
-     * Only source sets that are contained within _this project_ should be included here.
-     * To merge source sets from other projects, use the Gradle dependencies block.
-     *
-     * ```kotlin
-     * dependencies {
-     *   // merge :other-project into this project's Dokka Configuration
-     *   dokka(project(":other-project"))
-     * }
-     * ```
-     *
-     * Or, to include other Dokka Publications as a Dokka Module use
-     *
-     * ```kotlin
-     * dependencies {
-     *   // include :other-project as a module in this project's Dokka Configuration
-     *   dokkaModule(project(":other-project"))
-     * }
-     * ```
-     *
-     * Dokka will merge Dokka Source Sets from other subprojects if...
      */
     val dokkaSourceSets: NamedDomainObjectContainer<DokkaSourceSetSpec> =
         extensions.adding("dokkaSourceSets", objects.domainObjectContainer())
@@ -134,11 +132,8 @@ constructor(
      * [Gradle Worker](https://docs.gradle.org/8.5/userguide/worker_api.html).
      *
      * You can control whether Dokka Gradle Plugin launches Dokka Generator in
-     * * a new process, using [ProcessIsolation],
-     * * or the current process with an isolated classpath, using [ClassLoaderIsolation].
-     *
-     * _Aside: Launching [without isolation][WorkerExecutor.noIsolation] is not an option, because
-     * running Dokka Generator **requires** an isolated classpath._
+     * - a new process, using [ProcessIsolation],
+     * - or the current process with an isolated classpath, using [ClassLoaderIsolation].
      *
      * ```kotlin
      * dokka {
@@ -153,6 +148,9 @@ constructor(
      * }
      * ```
      *
+     * _Aside: Launching [without isolation][WorkerExecutor.noIsolation] is not an option, because
+     * running Dokka Generator **requires** an isolated classpath._
+     *
      * @see WorkerIsolation
      * @see org.jetbrains.dokka.gradle.workers.ProcessIsolation
      * @see org.jetbrains.dokka.gradle.workers.ClassLoaderIsolation
@@ -165,6 +163,8 @@ constructor(
      * Create a new [ClassLoaderIsolation] options instance.
      *
      * The resulting options must be set into [dokkaGeneratorIsolation].
+     *
+     * @see dokkaGeneratorIsolation
      */
     fun ClassLoaderIsolation(configure: ClassLoaderIsolation.() -> Unit = {}): ClassLoaderIsolation =
         objects.newInstance<ClassLoaderIsolation>().apply(configure)
@@ -173,6 +173,8 @@ constructor(
      * Create a new [ProcessIsolation] options.
      *
      * The resulting options instance must be set into [dokkaGeneratorIsolation].
+     *
+     * @see dokkaGeneratorIsolation
      */
     fun ProcessIsolation(configure: ProcessIsolation.() -> Unit = {}): ProcessIsolation =
         objects.newInstance<ProcessIsolation>().apply(configure)
@@ -180,6 +182,8 @@ constructor(
 
     //region deprecated properties
     /**
+     * This property has moved to be configured on each [DokkaPublication].
+     *
      * ```
      * dokka {
      *   // DEPRECATED
@@ -197,6 +201,9 @@ constructor(
     abstract val suppressInheritedMembers: Property<Boolean>
 
     /**
+     *
+     * This property has moved to be configured on each [DokkaPublication].
+     *
      * ```
      * dokka {
      *   // DEPRECATED
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/AndroidAdapter.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/AndroidAdapter.kt
index 293fd92959..445eaa0444 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/AndroidAdapter.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/AndroidAdapter.kt
@@ -27,6 +27,12 @@ import org.jetbrains.dokka.gradle.internal.artifactType
 import java.io.File
 import javax.inject.Inject
 
+/**
+ * Discovers Android Gradle Plugin specific configuration and uses it to configure Dokka.
+ *
+ * This is an internal Dokka plugin and should not be used externally.
+ * It is not a standalone plugin, it requires [org.jetbrains.dokka.gradle.DokkaBasePlugin] is also applied.
+ */
 @DokkaInternalApi
 abstract class AndroidAdapter @Inject constructor(
     private val objects: ObjectFactory,
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/JavaAdapter.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/JavaAdapter.kt
index eba6b6382e..95681d74a3 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/JavaAdapter.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/JavaAdapter.kt
@@ -30,7 +30,8 @@ import javax.inject.Inject
 /**
  * Discovers Java Gradle Plugin specific configuration and uses it to configure Dokka.
  *
- * **Must be applied *after* [org.jetbrains.dokka.gradle.DokkaBasePlugin]**
+ * This is an internal Dokka plugin and should not be used externally.
+ * It is not a standalone plugin, it requires [org.jetbrains.dokka.gradle.DokkaBasePlugin] is also applied.
  */
 @DokkaInternalApi
 abstract class JavaAdapter @Inject constructor(
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/KotlinAdapter.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/KotlinAdapter.kt
index ab7e188d1d..2cd22804d5 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/KotlinAdapter.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/KotlinAdapter.kt
@@ -47,7 +47,8 @@ import kotlin.reflect.jvm.jvmName
 /**
  * The [KotlinAdapter] plugin will automatically register Kotlin source sets as Dokka source sets.
  *
- * This is not a standalone plugin, it requires [org.jetbrains.dokka.gradle.DokkaBasePlugin] is also applied.
+ * This is an internal Dokka plugin and should not be used externally.
+ * It is not a standalone plugin, it requires [org.jetbrains.dokka.gradle.DokkaBasePlugin] is also applied.
  */
 @DokkaInternalApi
 abstract class KotlinAdapter @Inject constructor(
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt
index 2e9aa7a7d5..21ff431550 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt
@@ -40,12 +40,29 @@ interface DokkaAttribute {
 
     @DokkaInternalApi
     companion object {
+        /**
+         * Describes the type of generated output that Dokka generates.
+         *
+         * For example, HTML or Javadoc.
+         *
+         * @see DokkaAttribute.Format
+         */
         val DokkaFormatAttribute: Attribute<String> =
             Attribute("org.jetbrains.dokka.format")
 
+        /**
+         * Dokka Modules have several components that must be shared separately.
+         *
+         * @see DokkaAttribute.ModuleComponent
+         */
         val DokkaModuleComponentAttribute: Attribute<String> =
             Attribute("org.jetbrains.dokka.module-component")
 
+        /**
+         * Runtime JVM classpath for executing Dokka Generator.
+         *
+         * @see DokkaAttribute.Classpath
+         */
         val DokkaClasspathAttribute: Attribute<String> =
             Attribute("org.jetbrains.dokka.classpath")
     }
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/FormatDependenciesManager.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/FormatDependenciesManager.kt
index 2a0cc60f7f..b565cb6842 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/FormatDependenciesManager.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/FormatDependenciesManager.kt
@@ -101,13 +101,20 @@ class FormatDependenciesManager(
     //endregion
 
     //region Dokka Plugins for Publication Generation
+    /**
+     * Plugins specifically used to generate a Dokka Publication for a specific format (named [formatName]).
+     */
     private val dokkaPublicationPluginClasspath: NamedDomainObjectProvider<Configuration> =
         project.configurations.register(configurationNames.publicationPluginClasspath) {
-            description = "Dokka Plugins classpath for a $formatName Publication (consisting of one or more Dokka Modules)."
+            description =
+                "Dokka Plugins classpath for a $formatName Publication (consisting of one or more Dokka Modules)."
             declarable()
             extendsFrom(baseDependencyManager.declaredDependencies)
         }
 
+    /**
+     * Resolver for [dokkaPublicationPluginClasspath].
+     */
     val dokkaPublicationPluginClasspathResolver: Configuration =
         project.configurations.create(configurationNames.publicationPluginClasspathResolver) {
             description =
@@ -121,17 +128,28 @@ class FormatDependenciesManager(
             }
         }
 
+    /**
+     * Expose Dokka Publication Plugins required to create a Dokka Publication that aggregates a Dokka Module
+     * from the same dependency.
+     *
+     * For example, given a project `:lib-gamma` that is aggregated into subproject `:docs`.
+     * If `:lib-gamma` requires that a custom Dokka plugin is used _only_ when aggregating, then `:lib-gamma`
+     * can add the custom Dokka plugin into [dokkaPublicationPluginClasspathApiOnly].
+     * The plugin will only be used by `:docs`, and _not_ by `lib-gamma`.
+     *
+     * This is currently used to support HTML aggregation, using the 'All Modules plugin'.
+     */
     val dokkaPublicationPluginClasspathApiOnly: Configuration =
         project.configurations.create(configurationNames.publicationPluginClasspathApiOnly) {
             description =
-                "$INTERNAL_CONF_DESCRIPTION_TAG Dokka Plugins for consumers that will assemble a $formatName Publication using the Dokka Module that this project produces"
+                "$INTERNAL_CONF_DESCRIPTION_TAG Dokka Plugins for consumers that will assemble a $formatName Publication using the Dokka Module that this project produces."
             declarable()
         }
 
     init {
         project.configurations.create(configurationNames.publicationPluginClasspathApiOnlyConsumable) {
             description =
-                "$INTERNAL_CONF_DESCRIPTION_TAG Shared Dokka Plugins for consumers that will assemble a $formatName Publication using the Dokka Module that this project produces"
+                "$INTERNAL_CONF_DESCRIPTION_TAG Shared Dokka Plugins for consumers that will assemble a $formatName Publication using the Dokka Module that this project produces."
             consumable()
             extendsFrom(dokkaPublicationPluginClasspathApiOnly)
             attributes {
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/ModuleComponentDependencies.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/ModuleComponentDependencies.kt
index b32160c9c1..03a64e7303 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/ModuleComponentDependencies.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/ModuleComponentDependencies.kt
@@ -15,7 +15,13 @@ import org.jetbrains.dokka.gradle.dependencies.DokkaAttribute.Companion.DokkaMod
 import org.jetbrains.dokka.gradle.internal.*
 import java.io.File
 
-
+/**
+ * Manage sharing and receiving components used to build a Dokka Module.
+ *
+ * The type of component is determined by [component].
+ *
+ * Files are shared using variant-aware Gradle [Configuration]s.
+ */
 @DokkaInternalApi
 class ModuleComponentDependencies(
     project: Project,
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaExternalDocumentationLinkSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaExternalDocumentationLinkSpec.kt
index ff49995ab4..084081c688 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaExternalDocumentationLinkSpec.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaExternalDocumentationLinkSpec.kt
@@ -55,8 +55,14 @@ constructor(
      * Example:
      *
      * ```kotlin
-     * java.net.URI("https://kotlinlang.org/api/kotlinx.serialization/")
+     * url.set(java.net.URI("https://kotlinlang.org/api/kotlinx.serialization/"))
+     *
+     * // OR
+     *
+     * url("https://kotlinlang.org/api/kotlinx.serialization/")
      * ```
+     *
+     * @see url
      */
     @get:Input
     abstract val url: Property<URI>
@@ -65,6 +71,7 @@ constructor(
      * Set the value of [url].
      *
      * @param[value] will be converted to a [URI]
+     * @see url
      */
     fun url(@Language("http-url-reference") value: String): Unit =
         url.set(URI(value))
@@ -73,6 +80,7 @@ constructor(
      * Set the value of [url].
      *
      * @param[value] will be converted to a [URI]
+     * @see url
      */
     fun url(value: Provider<String>): Unit =
         url.set(value.map(::URI))
@@ -84,7 +92,7 @@ constructor(
      * Example:
      *
      * ```kotlin
-     * rootProject.projectDir.resolve("serialization.package.list").toURL()
+     * packageListUrl.set(rootProject.projectDir.resolve("serialization.package.list").toURI())
      * ```
      */
     @get:Input
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt
index 22a0abd2af..7dbcf721b1 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt
@@ -10,15 +10,21 @@ import org.gradle.api.plugins.ExtensionAware
 import org.gradle.api.provider.Property
 import org.gradle.api.tasks.*
 import org.gradle.api.tasks.PathSensitivity.RELATIVE
-import org.jetbrains.dokka.gradle.internal.DokkaPluginParametersContainer
 import org.jetbrains.dokka.gradle.internal.DokkaInternalApi
+import org.jetbrains.dokka.gradle.internal.DokkaPluginParametersContainer
 import org.jetbrains.dokka.gradle.internal.adding
 import org.jetbrains.dokka.gradle.internal.domainObjectContainer
 import javax.inject.Inject
 
 /**
- * Parameters used to run Dokka Generator to produce either a
- * Dokka Publication or a Dokka Module.
+ * Parameters used to run [org.jetbrains.dokka.DokkaGenerator] to produce either
+ * a Dokka Publication or a Dokka Module.
+ *
+ * This class is a bridge between configurable options and [org.jetbrains.dokka.DokkaConfiguration],
+ * and should only be used internally.
+ *
+ * Dokka users should use [org.jetbrains.dokka.gradle.DokkaExtension] to configure
+ * [DokkaSourceSetSpec] and [org.jetbrains.dokka.gradle.formats.DokkaPublication].
  */
 abstract class DokkaGeneratorParametersSpec
 @DokkaInternalApi
@@ -33,35 +39,32 @@ constructor(
     val pluginsConfiguration: DokkaPluginParametersContainer,
 ) : ExtensionAware {
 
-//  /** Dokka Configuration files from other subprojects that will be merged into this Dokka Configuration */
-//  @get:InputFiles
-//  //@get:NormalizeLineEndings
-//  @get:PathSensitive(PathSensitivity.RELATIVE)
-//  @get:Optional
-//  abstract val dokkaSubprojectParameters: ConfigurableFileCollection
-
-    @get:Input
-    abstract val failOnWarning: Property<Boolean>
-
-    @get:Input
-    abstract val finalizeCoroutines: Property<Boolean>
-
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.moduleName */
     @get:Input
     abstract val moduleName: Property<String>
 
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.moduleVersion */
     @get:Input
     @get:Optional
     abstract val moduleVersion: Property<String>
 
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.failOnWarning */
+    @get:Input
+    abstract val failOnWarning: Property<Boolean>
+
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.offlineMode */
     @get:Input
     abstract val offlineMode: Property<Boolean>
 
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.suppressObviousFunctions */
     @get:Input
     abstract val suppressObviousFunctions: Property<Boolean>
 
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.suppressInheritedMembers */
     @get:Input
     abstract val suppressInheritedMembers: Property<Boolean>
 
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.includes */
     @get:InputFiles
     @get:PathSensitive(RELATIVE)
     abstract val includes: ConfigurableFileCollection
@@ -89,4 +92,9 @@ constructor(
     @get:InputFiles
     @get:PathSensitive(RELATIVE)
     abstract val moduleOutputDirectories: ConfigurableFileCollection
+
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.finalizeCoroutines */
+    @DokkaInternalApi
+    @get:Input
+    abstract val finalizeCoroutines: Property<Boolean>
 }
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaModuleDescriptionKxs.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaModuleDescriptionKxs.kt
index 4859460de7..71828b4db1 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaModuleDescriptionKxs.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaModuleDescriptionKxs.kt
@@ -28,7 +28,7 @@ import org.jetbrains.dokka.gradle.internal.DokkaInternalApi
 data class DokkaModuleDescriptionKxs(
     /** @see DokkaConfiguration.DokkaModuleDescription.name */
     val name: String,
-    /** @see [org.gradle.api.Project.getPath] */
+    /** @see org.jetbrains.dokka.gradle.DokkaExtension.modulePath */
     val modulePath: String,
     /** name of the sibling directory that contains the module output */
     val moduleOutputDirName: String = "module",
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceLinkSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceLinkSpec.kt
index 8d3366bfd3..2ab748e50d 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceLinkSpec.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceLinkSpec.kt
@@ -55,7 +55,9 @@ constructor(
     abstract val localDirectory: DirectoryProperty
 
     /**
-     * The relative path to [localDirectory] from the project directory. Declared as an input to invalidate the task if that path changes.
+     * The relative path to [localDirectory] from the project directory.
+     *
+     * Declared as an [Input] only so Gradle will re-run the task if that path changes.
      * Should not be used anywhere directly.
      */
     @get:Input
@@ -73,24 +75,34 @@ constructor(
      * Example:
      *
      * ```kotlin
-     * java.net.URI("https://github.com/username/projectname/tree/master/src"))
+     * remoteUrl.set(java.net.URI("https://github.com/username/projectname/tree/master/src"))
+     *
+     * // OR
+     *
+     * remoteUrl("https://github.com/username/projectname/tree/master/src")
      * ```
+     *
+     * @see remoteUrl
      */
     @get:Input
     abstract val remoteUrl: Property<URI>
 
     /**
-     * Set the value of [remoteUrl].
+     * A remote URL of the hosted source code.
+     *
+     * [value] will be converted to a [URI].
      *
-     * @param[value] will be converted to a [URI]
+     * @see remoteUrl
      */
     fun remoteUrl(@Language("http-url-reference") value: String): Unit =
         remoteUrl.set(URI(value))
 
     /**
-     * Set the value of [remoteUrl].
+     * A remote URL of the hosted source code.
+     *
+     * [value] will be converted to a [URI].
      *
-     * @param[value] will be converted to a [URI]
+     * @see remoteUrl
      */
     fun remoteUrl(value: Provider<String>): Unit =
         remoteUrl.set(value.map(::URI))
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt
index dff239e7a9..68298c593e 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt
@@ -25,9 +25,11 @@ import javax.inject.Inject
 import kotlin.DeprecationLevel.ERROR
 
 /**
- * [Source set](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) level configuration.
+ * A [DokkaSourceSetSpec] controls how Dokka will view and rendered sources.
  *
- * Can be configured in the following way with Gradle Kotlin DSL:
+ * Dokka will automatically discover source sets from Kotlin, Android, and Java projects.
+ *
+ * Source sets can be configured individually, or all at once.
  *
  * ```kotlin
  * // build.gradle.kts
@@ -36,12 +38,12 @@ import kotlin.DeprecationLevel.ERROR
  *   dokkaSourceSets {
  *     // configure individual source set by name
  *     named("customSourceSet") {
- *       suppress.set(true)
+ *       // ...
  *     }
  *
  *     // configure all source sets at once
  *     configureEach {
- *       reportUndocumented.set(true)
+ *       // ...
  *     }
  *   }
  * }
@@ -77,7 +79,7 @@ constructor(
     abstract val sourceSetScope: Property<String>
 
     /**
-     * The identifier for this source set, across all Gradle subprojects.
+     * The identifier for this source set, which is distinct across all Gradle subprojects.
      *
      * @see sourceSetScope
      * @see getName
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/HasConfigurableVisibilityModifiers.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/HasConfigurableVisibilityModifiers.kt
index deac1003ab..19a3870025 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/HasConfigurableVisibilityModifiers.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/HasConfigurableVisibilityModifiers.kt
@@ -6,6 +6,9 @@ package org.jetbrains.dokka.gradle.engine.parameters
 import org.gradle.api.provider.SetProperty
 import org.gradle.api.tasks.Input
 
+/**
+ * Describes types that have customisable visibilities.
+ */
 internal interface HasConfigurableVisibilityModifiers {
 
     @get:Input
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/SourceSetIdSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/SourceSetIdSpec.kt
index ea917fe8c5..7061b64ef3 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/SourceSetIdSpec.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/SourceSetIdSpec.kt
@@ -12,19 +12,19 @@ import org.jetbrains.dokka.gradle.internal.DokkaInternalApi
 import java.io.Serializable
 import javax.inject.Inject
 
+/**
+ * An identifier for a [DokkaSourceSetSpec].
+ *
+ * The identifiers must be distinct for all source sets across an entire Gradle build,
+ * to ensure when Dokka Modules are aggregated into a Dokka Publication, the source sets can be
+ * uniquely identified.
+ */
 abstract class SourceSetIdSpec
 @DokkaInternalApi
 @Inject
 constructor(
     /**
      * Unique identifier of the scope that this source set is placed in.
-     * Each scope provide only unique source set names.
-     *
-     * TODO update this doc - DokkaTask doesn't represent one source set scope anymore
-     *
-     * E.g. One DokkaTask inside the Gradle plugin represents one source set scope, since there cannot be multiple
-     * source sets with the same name. However, a Gradle project will not be a proper scope, since there can be
-     * multiple DokkaTasks that contain source sets with the same name (but different configuration)
      */
     @get:Input
     val scopeId: String,
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaParametersBuilder.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaParametersBuilder.kt
index bfbcc05d95..fb0f4a7062 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaParametersBuilder.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaParametersBuilder.kt
@@ -117,7 +117,7 @@ internal class DokkaParametersBuilder(
                 // `relativeOutputDir` is the path where the Dokka Module should be located within the final
                 // Dokka Publication.
                 // Convert a project path to a relative path
-                // e.g. `:x:y:z:my-cool-subproject` -> `x/y/z/my-cool-subproject`.
+                // e.g. `:x:y:z:my-cool-subproject` → `x/y/z/my-cool-subproject`.
                 // The path has to be unique per module - using the project path is a useful way to achieve this.
                 val relativeOutputDir =
                     File(moduleDescriptor.modulePath.removePrefix(":").replace(':', '/'))
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaSourceSetBuilder.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaSourceSetBuilder.kt
index 4b397d1038..7216b87131 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaSourceSetBuilder.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaSourceSetBuilder.kt
@@ -3,7 +3,6 @@
  */
 package org.jetbrains.dokka.gradle.engine.parameters.builders
 
-
 import org.gradle.api.logging.Logging
 import org.jetbrains.dokka.*
 import org.jetbrains.dokka.gradle.engine.parameters.*
@@ -13,7 +12,6 @@ import org.jetbrains.dokka.gradle.internal.DokkaInternalApi
 import org.jetbrains.dokka.gradle.internal.mapNotNullToSet
 import org.jetbrains.dokka.gradle.internal.mapToSet
 
-
 /**
  * Convert the Gradle-focused [DokkaSourceSetSpec] into a [DokkaSourceSetImpl] instance, which
  * will be passed to Dokka Generator.
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
index ef0cbdb4ae..0b90a3611a 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
@@ -8,6 +8,7 @@ import org.gradle.api.file.ConfigurableFileCollection
 import org.gradle.api.file.DirectoryProperty
 import org.gradle.api.plugins.ExtensionAware
 import org.gradle.api.provider.Property
+import org.jetbrains.dokka.gradle.engine.parameters.DokkaSourceSetSpec
 import org.jetbrains.dokka.gradle.internal.DokkaInternalApi
 import org.jetbrains.dokka.gradle.internal.DokkaPluginParametersContainer
 import org.jetbrains.dokka.gradle.internal.adding
@@ -25,6 +26,13 @@ abstract class DokkaPublication
 @DokkaInternalApi
 @Inject
 constructor(
+    /**
+     * The identifier of the generated output format.
+     *
+     * For example, `html` or `javadoc`.
+     *
+     * The value is case-sensitive.
+     */
     val formatName: String,
 
     /**
@@ -38,30 +46,95 @@ constructor(
     val pluginsConfiguration: DokkaPluginParametersContainer =
         extensions.adding("pluginsConfiguration", pluginsConfiguration)
 
+    /** @see formatName */
     override fun getName(): String = formatName
 
+    /**
+     * Controls whether Dokka should generate documentation using this publication.
+     */
     abstract val enabled: Property<Boolean>
 
+    /** @see org.jetbrains.dokka.gradle.DokkaExtension.moduleName */
     abstract val moduleName: Property<String>
 
+    /** @see org.jetbrains.dokka.gradle.DokkaExtension.moduleVersion */
     abstract val moduleVersion: Property<String>
 
     /** Output directory for the finished Dokka publication. */
     abstract val outputDirectory: DirectoryProperty
 
-    abstract val cacheRoot: DirectoryProperty
-
+    /**
+     * Whether to resolve remote files/links over the network.
+     *
+     * This includes package-lists used for generating external documentation links.
+     * For example, to make classes from the standard library clickable in the generated output.
+     *
+     * Setting this to `true` can significantly speed up build times in certain cases,
+     * but can also worsen documentation quality and user experience.
+     * For example, by not resolving class/member links from your dependencies, including the standard library.
+     *
+     * Note: You can cache files locally and provide them to Dokka as local paths.
+     * See [DokkaSourceSetSpec.externalDocumentationLinks].
+     */
     abstract val offlineMode: Property<Boolean>
 
+    /**
+     * Whether to fail documentation generation if Dokka has emitted a warning or an error.
+     * The process waits until all errors and warnings have been emitted first.
+     *
+     * This setting works well with [DokkaSourceSetSpec.reportUndocumented].
+     */
     abstract val failOnWarning: Property<Boolean>
 
+    /**
+     * Whether to suppress obvious functions.
+     *
+     * A function is considered to be obvious if it is:
+     *
+     * - Inherited from [kotlin.Any], [kotlin.Enum], [java.lang.Object] or [java.lang.Enum],
+     *   such as `equals()`, `hashCode()`, `toString()` functions.
+     * - Synthetic (generated by the compiler) and does not have any documentation,
+     *   such as `data class` `componentN()` or `copy()` functions.
+     */
     abstract val suppressObviousFunctions: Property<Boolean>
 
+    /**
+     * Whether to suppress inherited members that aren't explicitly overridden in a given class.
+     *
+     * Note: This can suppress functions such as `equals()`, `hashCode()`, or `toString()`,
+     * but cannot suppress synthetic functions such as `data class` `componentN()` or `copy()`.
+     * Instead, use [suppressObviousFunctions].
+     */
+    abstract val suppressInheritedMembers: Property<Boolean>
+
+    /**
+     * A list of Markdown files that contain module and package documentation.
+     *
+     * The contents of the specified files are parsed and embedded into documentation as module and package descriptions.
+     *
+     * The format of the Markdown files is very specific and must be exactly correct to be readable by Dokka.
+     *
+     * See the
+     * [Dokka Gradle example](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/basic-gradle-example)
+     * for an example of what it looks like and how to use it.
+     */
     abstract val includes: ConfigurableFileCollection
 
-    abstract val suppressInheritedMembers: Property<Boolean>
+    /**
+     * A shared cache directory used by DokkaGenerator.
+     *
+     * (Aside: This property is not used by any official Dokka plugins.
+     * It has been retained in case third-party Dokka plugins use it.)
+     */
+    abstract val cacheRoot: DirectoryProperty
 
-    // TODO probably not needed any more, since Dokka Generator now runs in an isolated JVM process
+    /**
+     * Controls whether [org.jetbrains.dokka.DokkaGenerator] will forcibly stop coroutines.
+     *
+     * This is an internal Dokka Gradle plugin property.
+     * If you find you need to set this property, please report your use-case https://kotl.in/dokka-issues.
+     */
+    @DokkaInternalApi
     abstract val finalizeCoroutines: Property<Boolean>
 
     /** Output directory for the partial Dokka module. */
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/DokkaInternalApi.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/DokkaInternalApi.kt
index 661f6e286b..9ce1016439 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/DokkaInternalApi.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/DokkaInternalApi.kt
@@ -9,8 +9,8 @@ import kotlin.annotation.AnnotationTarget.*
 
 
 /**
- * Functionality annotated with this API is intended only for use by Dokka internal code,
- * but it has been given
+ * Functionality annotated with this API is intended only for use by the
+ * Dokka Gradle plugin, but it has been given
  * [`public` visibility](https://kotlinlang.org/docs/visibility-modifiers.html)
  * for technical reasons.
  *
@@ -23,7 +23,7 @@ import kotlin.annotation.AnnotationTarget.*
  * [the Dokka issue tracker](https://github.com/Kotlin/dokka/issues).
  */
 @RequiresOptIn(
-    message = "Internal Dokka API - may change at any time without notice",
+    message = "Internal Dokka Gradle API - may change at any time without notice",
     level = WARNING,
 )
 @Retention(BINARY)
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/HasFormatName.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/HasFormatName.kt
index 2801c56c2b..f32a21c3f1 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/HasFormatName.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/HasFormatName.kt
@@ -3,6 +3,9 @@
  */
 package org.jetbrains.dokka.gradle.internal
 
+/**
+ * The base type for types that specifically for a single Dokka output format (e.g. HTML or Javadoc).
+ */
 @DokkaInternalApi
 abstract class HasFormatName {
     abstract val formatName: String
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/DokkaGenerateTask.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/DokkaGenerateTask.kt
index 8a0e9e003a..1cabf4ae0c 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/DokkaGenerateTask.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/DokkaGenerateTask.kt
@@ -66,6 +66,7 @@ constructor(
     @get:Classpath
     abstract val runtimeClasspath: ConfigurableFileCollection
 
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.cacheRoot */
     @get:LocalState
     abstract val cacheDirectory: DirectoryProperty
 
@@ -87,6 +88,10 @@ constructor(
     @get:Nested
     abstract val workerIsolation: Property<WorkerIsolation>
 
+    /**
+     * All [org.jetbrains.dokka.DokkaGenerator] logs will be saved to this file.
+     * This can be used for debugging purposes.
+     */
     @get:Internal
     abstract val workerLogFile: RegularFileProperty
 
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/LogHtmlPublicationLinkTask.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/LogHtmlPublicationLinkTask.kt
index 6a97345817..0c2d338646 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/LogHtmlPublicationLinkTask.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/LogHtmlPublicationLinkTask.kt
@@ -28,7 +28,6 @@ import javax.inject.Inject
  * [IntelliJ's built-in server](https://www.jetbrains.com/help/phpstorm/php-built-in-web-server.html#ws_html_preview_output_built_in_browser)†
  * to host the file.
  *
- *
  * This task can be disabled using the [ENABLE_TASK_PROPERTY_NAME] project property.
  *
  * ---
@@ -63,19 +62,19 @@ constructor(
      *
      * For example,
      *
-     * * given an IntelliJ project named `MyProject` located in a directory:
+     * - given an IntelliJ project named `MyProject` located in a directory:
      *    ```
      *    /Users/rachel/projects/my-project/
      *    ```
-     * * and the publication is generated with an index file
+     * - and the publication is generated with an index file
      *    ```
      *    /Users/rachel/projects/my-project/docs/build/dokka/html/index.html
      *    ````
-     * * then [indexHtmlPath] must be
+     * - then [indexHtmlPath] must be
      *    ```
      *    docs/build/dokka/html/index.html
      *    ```
-     * * so that (assuming [serverUri] is `http://localhost:63342`) the logged URL is
+     * - so that (assuming [serverUri] is `http://localhost:63342`) the logged URL is
      *    ```
      *    http://localhost:63342/MyProject/docs/build/dokka/html/index.html
      *    ```
@@ -176,22 +175,23 @@ constructor(
             }
         }
 
-//        private fun httpGetStatusJdk11(uri: URI): Result<Int> {
-//            try {
-//                val client = java.net.http.HttpClient.newHttpClient()
-//                val request = java.net.http.HttpRequest
-//                    .newBuilder()
-//                    .uri(uri)
-//                    .timeout(Duration.ofSeconds(1))
-//                    .GET()
-//                    .build()
-//                // don't care about the status - only if the server is available
-//                val response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString())
-//                return Result.success(response.statusCode())
-//            } catch (ex: Exception) {
-//                return Result.failure(ex)
-//            }
-//        }
+        // When the minimum supported Java version is 11+
+        //private fun httpGetStatusJdk11(uri: URI): Result<Int> {
+        //    try {
+        //        val client = java.net.http.HttpClient.newHttpClient()
+        //        val request = java.net.http.HttpRequest
+        //            .newBuilder()
+        //            .uri(uri)
+        //            .timeout(Duration.ofSeconds(1))
+        //            .GET()
+        //            .build()
+        //        // don't care about the status - only if the server is available
+        //        val response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString())
+        //        return Result.success(response.statusCode())
+        //    } catch (ex: Exception) {
+        //        return Result.failure(ex)
+        //    }
+        //}
     }
 
     companion object {
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/TaskNames.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/TaskNames.kt
index 8d76d046bf..c7f9614f41 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/TaskNames.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/TaskNames.kt
@@ -6,6 +6,9 @@ package org.jetbrains.dokka.gradle.tasks
 import org.jetbrains.dokka.gradle.internal.DokkaInternalApi
 import org.jetbrains.dokka.gradle.internal.HasFormatName
 
+/**
+ * Gradle [Task][org.gradle.api.Task] Names for a specific Dokka output format.
+ */
 @DokkaInternalApi
 class TaskNames(override val formatName: String) : HasFormatName() {
     val generate = "dokkaGenerate".appendFormat()

From b6f5ca31e3d4dffc702989672b5eee81977aba58 Mon Sep 17 00:00:00 2001
From: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>
Date: Wed, 2 Oct 2024 16:02:23 +0200
Subject: [PATCH 02/12] unmark `finalizeCoroutines` as internal

---
 .../kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt     | 1 -
 .../src/main/kotlin/formats/DokkaPublication.kt                  | 1 -
 2 files changed, 2 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt
index 7dbcf721b1..3c8f43db99 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt
@@ -94,7 +94,6 @@ constructor(
     abstract val moduleOutputDirectories: ConfigurableFileCollection
 
     /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.finalizeCoroutines */
-    @DokkaInternalApi
     @get:Input
     abstract val finalizeCoroutines: Property<Boolean>
 }
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
index 0b90a3611a..f3d59b883f 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
@@ -134,7 +134,6 @@ constructor(
      * This is an internal Dokka Gradle plugin property.
      * If you find you need to set this property, please report your use-case https://kotl.in/dokka-issues.
      */
-    @DokkaInternalApi
     abstract val finalizeCoroutines: Property<Boolean>
 
     /** Output directory for the partial Dokka module. */

From ff37a2d6eb52e5e9c702d3f2061d60dd8c80ccc1 Mon Sep 17 00:00:00 2001
From: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>
Date: Mon, 14 Oct 2024 18:24:02 +0200
Subject: [PATCH 03/12] move comment out of kdoc

---
 .../dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt  | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index 378e66b220..94369ccba3 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -11,7 +11,6 @@ import org.gradle.api.plugins.ExtensionAware
 import org.gradle.api.provider.Property
 import org.gradle.api.tasks.Nested
 import org.gradle.kotlin.dsl.newInstance
-import org.gradle.workers.WorkerExecutor
 import org.jetbrains.dokka.gradle.dependencies.BaseDependencyManager
 import org.jetbrains.dokka.gradle.engine.parameters.DokkaSourceSetSpec
 import org.jetbrains.dokka.gradle.formats.DokkaPublication
@@ -148,14 +147,12 @@ constructor(
      * }
      * ```
      *
-     * _Aside: Launching [without isolation][WorkerExecutor.noIsolation] is not an option, because
-     * running Dokka Generator **requires** an isolated classpath._
-     *
      * @see WorkerIsolation
      * @see org.jetbrains.dokka.gradle.workers.ProcessIsolation
      * @see org.jetbrains.dokka.gradle.workers.ClassLoaderIsolation
-     *
      */
+    // Aside: Launching without isolation WorkerExecutor.noIsolation is not an option, because
+    // running Dokka Generator **requires** an isolated classpath.
     @get:Nested
     abstract val dokkaGeneratorIsolation: Property<WorkerIsolation>
 

From b760d4c59015c1c64f5e8959ce1f5b1aeb4a3219 Mon Sep 17 00:00:00 2001
From: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>
Date: Mon, 14 Oct 2024 18:35:09 +0200
Subject: [PATCH 04/12] DokkaPublication kdoc: Add defaults, and minor fixes

---
 .../main/kotlin/formats/DokkaPublication.kt   | 28 ++++++++++++++++---
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
index f3d59b883f..475472af14 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt
@@ -16,7 +16,7 @@ import java.io.Serializable
 import javax.inject.Inject
 
 /**
- * A [DokkaPublication] controls the output running the Dokka Generator.
+ * A [DokkaPublication] controls the output produced by the Dokka Generator.
  *
  * The output format (for example, HTML) is determined by the Dokka Plugins that are present.
  *
@@ -51,6 +51,8 @@ constructor(
 
     /**
      * Controls whether Dokka should generate documentation using this publication.
+     *
+     * Default: `true`
      */
     abstract val enabled: Property<Boolean>
 
@@ -60,11 +62,16 @@ constructor(
     /** @see org.jetbrains.dokka.gradle.DokkaExtension.moduleVersion */
     abstract val moduleVersion: Property<String>
 
-    /** Output directory for the finished Dokka publication. */
+    /**
+     * The output directory for the finished Dokka publication.
+     *
+     * Default: a subdirectory named [formatName] inside of
+     * [org.jetbrains.dokka.gradle.DokkaExtension.dokkaPublicationDirectory].
+     */
     abstract val outputDirectory: DirectoryProperty
 
     /**
-     * Whether to resolve remote files/links over the network.
+     * Whether Dokka is permitted to resolve remote files or links from the network.
      *
      * This includes package-lists used for generating external documentation links.
      * For example, to make classes from the standard library clickable in the generated output.
@@ -75,6 +82,8 @@ constructor(
      *
      * Note: You can cache files locally and provide them to Dokka as local paths.
      * See [DokkaSourceSetSpec.externalDocumentationLinks].
+     *
+     * Default: `false`
      */
     abstract val offlineMode: Property<Boolean>
 
@@ -83,6 +92,8 @@ constructor(
      * The process waits until all errors and warnings have been emitted first.
      *
      * This setting works well with [DokkaSourceSetSpec.reportUndocumented].
+     *
+     * Default: `false`
      */
     abstract val failOnWarning: Property<Boolean>
 
@@ -95,6 +106,8 @@ constructor(
      *   such as `equals()`, `hashCode()`, `toString()` functions.
      * - Synthetic (generated by the compiler) and does not have any documentation,
      *   such as `data class` `componentN()` or `copy()` functions.
+     *
+     * Default: `true`
      */
     abstract val suppressObviousFunctions: Property<Boolean>
 
@@ -104,6 +117,8 @@ constructor(
      * Note: This can suppress functions such as `equals()`, `hashCode()`, or `toString()`,
      * but cannot suppress synthetic functions such as `data class` `componentN()` or `copy()`.
      * Instead, use [suppressObviousFunctions].
+     *
+     * Default: `false`
      */
     abstract val suppressInheritedMembers: Property<Boolean>
 
@@ -136,6 +151,11 @@ constructor(
      */
     abstract val finalizeCoroutines: Property<Boolean>
 
-    /** Output directory for the partial Dokka module. */
+    /**
+     * Output directory for the partial Dokka module.
+     *
+     * Default: a subdirectory named [formatName] inside of
+     * [org.jetbrains.dokka.gradle.DokkaExtension.dokkaPublicationDirectory].
+     */
     internal abstract val moduleOutputDirectory: DirectoryProperty
 }

From 8d775c6a15cbc62b8d7ffaafb34aa44a244048b8 Mon Sep 17 00:00:00 2001
From: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>
Date: Mon, 14 Oct 2024 19:11:50 +0200
Subject: [PATCH 05/12] add more docs to modulePath

---
 .../src/main/kotlin/DokkaExtension.kt         | 22 +++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index 94369ccba3..ec1c52f031 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -60,10 +60,24 @@ constructor(
     abstract val moduleVersion: Property<String>
 
     /**
-     * A distinct relative path for the Dokka Module produced by the current project.
-     *
-     * Used in Dokka Publications to ensure the files produced by every Dokka Modules
-     * are in their own separate directories.
+     * Control the subdirectory used for files when aggregating this project as a Dokka Module into a Dokka Publication.
+     *
+     * When Dokka performs aggregation the files from each Module must be placed into separate
+     * subdirectories, within the Publication directory.
+     * The subdirectory used for this project's Module can be specified with this property.
+     *
+     * Overriding this value can be useful for fine-grained control.
+     * - Setting an explicit path can help ensure that external hyperlinks to the Publication are stable,
+     *   regardless of how the current Gradle project is structured.
+     * - The path can also be made more specific, which is useful for
+     *   [Composite Builds](https://docs.gradle.org/current/userguide/composite_builds.html),
+     *   which can be more likely to cause Module clashes.
+     *   (The default value is distinct for a single Gradle build. With composite builds the project paths may not be distinct.)
+     *   See the [Composite Build Example](https://github.com/Kotlin/dokka/tree/v2.0.0-Beta/examples/gradle-v2/composite-build-example#distinct-module-paths).
+     *
+     * **Important:** Care must be taken to make sure multiple Dokka Modules do not have the same paths.
+     * If paths overlap then Dokka could overwrite the Modules files during aggregation,
+     * resulting in a corrupted Publication.
      *
      * Default: the current project's path ([org.gradle.api.Project.getPath]) as a file path.
      */

From 67963a210acb1beba176acaed912a6dbcab5fbbc Mon Sep 17 00:00:00 2001
From: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>
Date: Tue, 15 Oct 2024 11:29:43 +0200
Subject: [PATCH 06/12] update dokkaGeneratorIsolation kdoc

---
 .../src/main/kotlin/DokkaExtension.kt         | 46 +++++++++++++++++--
 .../workers/WorkerIsolationProperties.kt      |  2 +-
 2 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index ec1c52f031..7c1306acdf 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -142,11 +142,49 @@ constructor(
 
     /**
      * Dokka Gradle Plugin runs Dokka Generator in a separate
-     * [Gradle Worker](https://docs.gradle.org/8.5/userguide/worker_api.html).
+     * [Gradle Worker](https://docs.gradle.org/8.10/userguide/worker_api.html).
      *
-     * You can control whether Dokka Gradle Plugin launches Dokka Generator in
-     * - a new process, using [ProcessIsolation],
-     * - or the current process with an isolated classpath, using [ClassLoaderIsolation].
+     * DGP uses a Worker to ensure that the Java classpath required by Dokka Generator
+     * is kept separate from the Gradle buildscript classpath, ensuring that dependencies
+     * required for running Gradle builds don't interfere with those needed to run Dokka.
+     *
+     * #### Worker modes
+     *
+     * DGP can launch the Generator in one of two Worker modes.
+     *
+     * The Worker modes are used to optimise the performance of a Gradle build,
+     * especially concerning the memory requirements.
+     *
+     * ##### [ProcessIsolation]
+     *
+     * The maximum isolation level. Dokka Generator is executed in a separate Java process,
+     * managed by Gradle.
+     *
+     * The Java process parameters (such as JVM args and system properties) can be configured precisely,
+     * and independently of other Gradle processes.
+     *
+     * Process isolation is best suited for projects where Dokka requires a lot more, or less,
+     * memory than other Gradle tasks that are run more frequently.
+     * This is usually the case for smaller projects, or those with default or low
+     * [Gradle Daemon](https://docs.gradle.org/8.10/userguide/gradle_daemon.html)
+     * memory settings.
+     *
+     * When the more frequent tasks are run, Gradle can use the default or lower memory requirements,
+     * and when Dokka is run then Gradle can request more memory. The result is better build performance.
+     *
+     * ##### [ClassLoaderIsolation]
+     *
+     * Dokka Generator is run in the current Gradle Daemon process, in a new thread with an isolated classpath.
+     *
+     * Classloader isolation is best suited for projects that already have high Gradle Daemon memory requirements.
+     * This is usually the case for very large projects, especially Kotlin Multiplatform projects.
+     * These projects will typically also require a lot of memory to running Dokka Generator.
+     *
+     * If the Gradle Daemon already uses a large amount of memory, it is beneficial to run Dokka Generator
+     * in the same Daemon process. Running Dokka Generator inside the Daemon avoids launching
+     * two Java processes on the same machine, both with high memory requirements.
+     *
+     * #### Example configuration
      *
      * ```kotlin
      * dokka {
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/workers/WorkerIsolationProperties.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/workers/WorkerIsolationProperties.kt
index 1795536592..33e49672f3 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/workers/WorkerIsolationProperties.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/workers/WorkerIsolationProperties.kt
@@ -38,7 +38,7 @@ sealed class WorkerIsolation {
      * Create a Worker using [process isolation][WorkerExecutor.processIsolation].
      *
      * Gradle will launch
-     * [new Worker Daemon](https://docs.gradle.org/8.5/userguide/worker_api.html#creating_a_worker_daemon)
+     * [new Worker Daemon](https://docs.gradle.org/8.10/userguide/worker_api.html#worker-daemons),
      * re-using it across builds.
      *
      * @see org.gradle.workers.ProcessWorkerSpec

From cca7e7ba6af83b62c9ff7b1e9190be617d9933a4 Mon Sep 17 00:00:00 2001
From: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>
Date: Wed, 16 Oct 2024 17:34:13 +0200
Subject: [PATCH 07/12] more docs...

---
 .../src/main/kotlin/DokkaExtension.kt         | 60 +++++++++++++++++--
 1 file changed, 56 insertions(+), 4 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index 7c1306acdf..ab5334d8e1 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -71,7 +71,7 @@ constructor(
      *   regardless of how the current Gradle project is structured.
      * - The path can also be made more specific, which is useful for
      *   [Composite Builds](https://docs.gradle.org/current/userguide/composite_builds.html),
-     *   which can be more likely to cause Module clashes.
+     *   which can be more likely to cause path clashes.
      *   (The default value is distinct for a single Gradle build. With composite builds the project paths may not be distinct.)
      *   See the [Composite Build Example](https://github.com/Kotlin/dokka/tree/v2.0.0-Beta/examples/gradle-v2/composite-build-example#distinct-module-paths).
      *
@@ -104,11 +104,34 @@ constructor(
     abstract val konanHome: RegularFileProperty
 
     /**
-     * Configuration for creating Dokka Publications.
+     * The container for all [DokkaPublication]s in the current project.
      *
-     * Each publication will generate one Dokka site based on the included Dokka Source Sets.
+     * Each Dokka Publication will generate one complete Dokka site,
+     * aggregated from one or more Dokka Modules.
      *
      * The type of site is determined by the Dokka Plugins. By default, an HTML site will be generated.
+     *
+     * #### Configuration
+     *
+     * To configure a specific Dokka Publications, select it by name:
+     *
+     * ```
+     * dokka {
+     *   dokkaPublications.named("html") {
+     *     // ...
+     *   }
+     * }
+     * ```
+     *
+     * All configurations can be configured using `.configureEach {}`:
+     *
+     * ```
+     * dokka {
+     *   dokkaPublications.configureEach {
+     *     // ...
+     *   }
+     * }
+     * ```
      */
     val dokkaPublications: NamedDomainObjectContainer<DokkaPublication> =
         extensions.adding(
@@ -117,9 +140,38 @@ constructor(
         )
 
     /**
-     * Dokka Source Sets describe the source code that should be included in the generated output.
+     * The container for all [DokkaSourceSet][DokkaSourceSetSpec]s in the current project.
+     *
+     * Each `DokkaSourceSet` is analogous to a [SourceSet][org.gradle.api.tasks.SourceSet],
+     * and specifies how Dokka will convert the project's source code into documentation.
+     *
+     * Dokka will automatically discover the current source sets in the project and create
+     * a `DokkaSourceSet` for each. For example, in a Kotlin Multiplatform project Dokka
+     * will create `DokkaSourceSet`s for `commonMain`, `jvmMain` etc.
      *
      * Dokka will not generate documentation unless there is at least there is at least one Dokka Source Set.
+     *
+     * #### Configuration
+     *
+     * To configure a specific Dokka Source Set, select it by name:
+     *
+     * ```
+     * dokka {
+     *   dokkaSourceSets.named("commonMain") {
+     *     // ...
+     *   }
+     * }
+     * ```
+     *
+     * All Source Sets can be configured using `.configureEach {}`:
+     *
+     * ```
+     * dokka {
+     *   dokkaSourceSets.configureEach {
+     *     // ...
+     *   }
+     * }
+     * ```
      */
     val dokkaSourceSets: NamedDomainObjectContainer<DokkaSourceSetSpec> =
         extensions.adding("dokkaSourceSets", objects.domainObjectContainer())

From 67057d6539ddfe3f6efba10fb4ab90993f48ca14 Mon Sep 17 00:00:00 2001
From: Adam <152864218+adam-enko@users.noreply.github.com>
Date: Thu, 17 Oct 2024 14:27:45 +0200
Subject: [PATCH 08/12] Update links in kdoc

Co-authored-by: Yahor Berdnikau <Ky4eP9IBbIu@gmail.com>
---
 .../dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt   | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index ab5334d8e1..fda76b0cff 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -48,14 +48,14 @@ constructor(
      * The display name used to refer to the module.
      * It is used for the table of contents, navigation, logging, etc.
      *
-     * Default: the current project name.
+     * Default: the [current project name][org.gradle.api.Project.name].
      */
     abstract val moduleName: Property<String>
 
     /**
      * The displayed module version.
      *
-     * Default: the version of the current project.
+     * Default: the [version of the current project][org.gradle.api.Project.version].
      */
     abstract val moduleVersion: Property<String>
 
@@ -79,7 +79,7 @@ constructor(
      * If paths overlap then Dokka could overwrite the Modules files during aggregation,
      * resulting in a corrupted Publication.
      *
-     * Default: the current project's path ([org.gradle.api.Project.getPath]) as a file path.
+     * Default: the current project's [path][org.gradle.api.Project.getPath] as a file path.
      */
     abstract val modulePath: Property<String>
 

From 768bedbba649f516a9c176d1606b36166e9b4f91 Mon Sep 17 00:00:00 2001
From: Adam <152864218+adam-enko@users.noreply.github.com>
Date: Thu, 17 Oct 2024 14:49:07 +0200
Subject: [PATCH 09/12] Add shortlink for composite build example

---
 .../dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index fda76b0cff..28eab676cd 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -73,7 +73,7 @@ constructor(
      *   [Composite Builds](https://docs.gradle.org/current/userguide/composite_builds.html),
      *   which can be more likely to cause path clashes.
      *   (The default value is distinct for a single Gradle build. With composite builds the project paths may not be distinct.)
-     *   See the [Composite Build Example](https://github.com/Kotlin/dokka/tree/v2.0.0-Beta/examples/gradle-v2/composite-build-example#distinct-module-paths).
+     *   See the [Composite Build Example](https://kotl.in/dokka/examples/gradle-composite-build).
      *
      * **Important:** Care must be taken to make sure multiple Dokka Modules do not have the same paths.
      * If paths overlap then Dokka could overwrite the Modules files during aggregation,

From a207576373c6bcefbca89be837a5e370f1440ad6 Mon Sep 17 00:00:00 2001
From: Adam <152864218+adam-enko@users.noreply.github.com>
Date: Thu, 17 Oct 2024 15:01:36 +0200
Subject: [PATCH 10/12] Add links to Dokka HTML and Javadoc docs

---
 .../src/main/kotlin/dependencies/DokkaAttribute.kt              | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt
index 21ff431550..0035694c4c 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/DokkaAttribute.kt
@@ -43,7 +43,7 @@ interface DokkaAttribute {
         /**
          * Describes the type of generated output that Dokka generates.
          *
-         * For example, HTML or Javadoc.
+         * For example, [HTML](https://kotl.in/dokka-html) or [Javadoc](https://kotl.in/dokka-javadoc).
          *
          * @see DokkaAttribute.Format
          */

From e690f543910a5cf59cb9c21856896e4da049ef9f Mon Sep 17 00:00:00 2001
From: Adam <152864218+adam-enko@users.noreply.github.com>
Date: Thu, 24 Oct 2024 16:43:14 +0200
Subject: [PATCH 11/12] fix typo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Gaëtan Muller <m.gaetan89@gmail.com>
---
 .../dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index dc9ceb5a91..30a89e47ca 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -166,7 +166,7 @@ constructor(
      * a `DokkaSourceSet` for each. For example, in a Kotlin Multiplatform project Dokka
      * will create `DokkaSourceSet`s for `commonMain`, `jvmMain` etc.
      *
-     * Dokka will not generate documentation unless there is at least there is at least one Dokka Source Set.
+     * Dokka will not generate documentation unless there is at least one Dokka Source Set.
      *
      * #### Configuration
      *

From 3552f51770fbf06071a97f740dcb11e33106bdd9 Mon Sep 17 00:00:00 2001
From: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>
Date: Thu, 31 Oct 2024 10:56:00 +0100
Subject: [PATCH 12/12] Remove summary paragraph about Worker performance. (Due
 to JIT/intra-process comms/process startup the performance isn't necessarily
 better.)

---
 .../dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt      | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
index 30a89e47ca..76622789e4 100644
--- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
+++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -238,9 +238,6 @@ constructor(
      * [Gradle Daemon](https://docs.gradle.org/8.10/userguide/gradle_daemon.html)
      * memory settings.
      *
-     * When the more frequent tasks are run, Gradle can use the default or lower memory requirements,
-     * and when Dokka is run then Gradle can request more memory. The result is better build performance.
-     *
      * ##### [ClassLoaderIsolation]
      *
      * Dokka Generator is run in the current Gradle Daemon process, in a new thread with an isolated classpath.