Kotlin · adam-enko · Oct 31, 2024 · Oct 2, 2024 · Oct 2, 2024 · Oct 14, 2024
diff --git 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
@@ -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,13 +173,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 +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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/...a-runners/dokka-gradle-plugin/src/main/kotlin/dependencies/ModuleComponentDependencies.kt b/...a-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/...kka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaExternalDocumentationLinkSpec.kt b/...kka-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/...ers/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaGeneratorParametersSpec.kt b/...ers/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,8 @@ constructor(
     @get:InputFiles
     @get:PathSensitive(RELATIVE)
     abstract val moduleOutputDirectories: ConfigurableFileCollection
+
+    /** @see org.jetbrains.dokka.gradle.formats.DokkaPublication.finalizeCoroutines */
+    @get:Input
+    abstract val finalizeCoroutines: Property<Boolean>
 }
diff --git a/...unners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaModuleDescriptionKxs.kt b/...unners/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",