Update and add KDoc for DGPv2

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)
         }
 

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
@@ -45,8 +44,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.
+     */
     abstract val moduleName: Property<String>
+
+    /**
+     * The displayed module version.
+     *
+     * Default: the version of the current project.
+     */
     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 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.
+     */
     abstract val modulePath: Property<String>
 
     /**
@@ -83,32 +117,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())
@@ -131,14 +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).
+     *
+     * 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.
      *
-     * 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].
+     * 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.
      *
-     * _Aside: Launching [without isolation][WorkerExecutor.noIsolation] is not an option, because
-     * running Dokka Generator **requires** an isolated classpath._
+     * 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 {
@@ -156,15 +202,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)
@@ -173,13 +222,17 @@ 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)
 
 
     //region deprecated properties
     /**
+     * This property has moved to be configured on each [DokkaPublication].
+     *
      * ```
      * dokka {
      *   // DEPRECATED
@@ -197,6 +250,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 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")
     }

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,

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