Update and add KDoc for DGPv2 (#3842)

KT-71890

---------

Co-authored-by: Yahor Berdnikau <Ky4eP9IBbIu@gmail.com>
Co-authored-by: Gaëtan Muller <m.gaetan89@gmail.com>

dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt

@@ -102,9 +102,6 @@ constructor(
             sourceSetScopeDefault.convention(project.path)
             basePublicationsDirectory.convention(layout.buildDirectory.dir("dokka"))
             baseModulesDirectory.convention(layout.buildDirectory.dir("dokka-module"))
-//            @Suppress("DEPRECATION")
-//            dokkaConfigurationsDirectory.convention(layout.buildDirectory.dir("dokka-config"))
-
             dokkaEngineVersion.convention(DokkaConstants.DOKKA_VERSION)
         }
 

dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt

@@ -12,7 +12,6 @@ import org.gradle.api.provider.MapProperty
 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
@@ -62,8 +61,43 @@ 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][org.gradle.api.Project.name].
+     */
     abstract val moduleName: Property<String>
+
+    /**
+     * The displayed module version.
+     *
+     * Default: the [version of the current project][org.gradle.api.Project.version].
+     */
     abstract val moduleVersion: Property<String>
+
+    /**
+     * 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 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://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,
+     * resulting in a corrupted Publication.
+     *
+     * Default: the current project's [path][org.gradle.api.Project.getPath] as a file path.
+     */
     abstract val modulePath: Property<String>
 
     /**
@@ -87,11 +121,34 @@ constructor(
     abstract val konanHome: RegularFileProperty
 
     /**
-     * Configuration for creating Dokka Publications.
+     * The container for all [DokkaPublication]s in the current project.
+     *
+     * Each Dokka Publication will generate one complete Dokka site,
+     * aggregated from one or more Dokka Modules.
      *
-     * Each publication will generate one Dokka site based on the included Dokka Source Sets.
+     * The type of site is determined by the Dokka Plugins. By default, an HTML site will be generated.
      *
-     * 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(
@@ -100,32 +157,38 @@ constructor(
         )
 
     /**
-     * Dokka Source Sets describe the source code that should be included in a Dokka Publication.
+     * The container for all [DokkaSourceSet][DokkaSourceSetSpec]s in the current project.
      *
-     * Dokka will not generate documentation unless there is at least there is at least one Dokka Source Set.
+     * 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.
      *
-     *  TODO make sure dokkaSourceSets doc is up to date...
+     * 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.
      *
-     * 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.
+     * Dokka will not generate documentation unless there is at least one Dokka Source Set.
      *
-     * ```kotlin
-     * dependencies {
-     *   // merge :other-project into this project's Dokka Configuration
-     *   dokka(project(":other-project"))
+     * #### Configuration
+     *
+     * To configure a specific Dokka Source Set, select it by name:
+     *
+     * ```
+     * dokka {
+     *   dokkaSourceSets.named("commonMain") {
+     *     // ...
+     *   }
      * }
      * ```
      *
-     * Or, to include other Dokka Publications as a Dokka Module use
+     * All Source Sets can be configured using `.configureEach {}`:
      *
-     * ```kotlin
-     * dependencies {
-     *   // include :other-project as a module in this project's Dokka Configuration
-     *   dokkaModule(project(":other-project"))
+     * ```
+     * dokka {
+     *   dokkaSourceSets.configureEach {
+     *     // ...
+     *   }
      * }
      * ```
-     *
-     * Dokka will merge Dokka Source Sets from other subprojects if...
      */
     val dokkaSourceSets: NamedDomainObjectContainer<DokkaSourceSetSpec> =
         extensions.adding("dokkaSourceSets", objects.domainObjectContainer())
@@ -148,14 +211,46 @@ 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).
+     *
+     * 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.
      *
-     * 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].
+     * ##### [ProcessIsolation]
      *
-     * _Aside: Launching [without isolation][WorkerExecutor.noIsolation] is not an option, because
-     * running Dokka Generator **requires** an isolated classpath._
+     * 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.
+     *
+     * ##### [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 {
@@ -173,15 +268,18 @@ constructor(
      * @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>
 
     /**
      * 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)
@@ -190,6 +288,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)
@@ -208,6 +308,8 @@ constructor(
         get() = basePublicationsDirectory
 
     /**
+     * This property has moved to be configured on each [DokkaPublication].
+     *
      * ```
      * dokka {
      *   // DEPRECATED
@@ -225,6 +327,9 @@ constructor(
     abstract val suppressInheritedMembers: Property<Boolean>
 
     /**
+     *
+     * This property has moved to be configured on each [DokkaPublication].
+     *
      * ```
      * dokka {
      *   // DEPRECATED

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,

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(

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(

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](https://kotl.in/dokka-html) or [Javadoc](https://kotl.in/dokka-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")
     }

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 {

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,