Revise documentation (#2728)

Co-authored-by: Sarah Haggarty <sarahhaggarty@users.noreply.github.com>

8 files changed, 634 insertions, 61 deletions

diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt
index 2c761eef..0fb62b30 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt
@@ -23,48 +23,160 @@ import kotlin.reflect.full.createInstance
 @DisableCachingByDefault(because = "Abstract super-class, not to be instantiated directly")
 abstract class AbstractDokkaTask : DefaultTask() {
 
+    /**
+     * Display name used to refer to the module. Used for ToC, navigation, logging, etc.
+     *
+     * If set for a single-project build or a MultiModule task, will be used as project name.
+     *
+     * Default is Gradle project name.
+     */
     @Input
     val moduleName: Property<String> = project.objects.safeProperty<String>()
         .safeConvention(project.name)
 
+    /**
+     * Module version.
+     *
+     * If set for a single-project build or a MultiModule task, will be used
+     * as project version by the versioning plugin.
+     *
+     * Default is Gradle project version.
+     */
     @Input
     val moduleVersion: Property<String> = project.objects.safeProperty<String>()
         .safeConvention(project.version.toString())
 
+    /**
+     * Directory to which documentation will be generated, regardless of format.
+     * Can be set on per-task basis.
+     *
+     * Default is `project/buildDir/taskName.removePrefix("dokka").decapitalize()`, so
+     * for `dokkaHtmlMultiModule` task it will be `project/buildDir/htmlMultiModule`
+     */
     @OutputDirectory
     val outputDirectory: Property<File> = project.objects.safeProperty<File>()
         .safeConvention(project.provider { defaultDokkaOutputDirectory() })
 
-    @Optional
-    @InputDirectory
-    @PathSensitive(PathSensitivity.RELATIVE)
-    val cacheRoot: Property<File?> = project.objects.safeProperty()
+    /**
+     * Configuration for Dokka plugins. This property is not expected to be used directly - if possible, use
+     * [pluginConfiguration] blocks (preferred) or [pluginsMapConfiguration] instead.
+     */
+    @Input
+    val pluginsConfiguration: ListProperty<in DokkaConfiguration.PluginConfiguration> = project.objects.listProperty()
 
+    /**
+     * JSON configuration of Dokka plugins.
+     *
+     * Key is fully qualified Dokka plugin name, value is its configuration in JSON.
+     *
+     * Example:
+     *
+     * ```kotlin
+     * tasks.dokkaHtml {
+     *     val dokkaBaseConfiguration = """
+     *     {
+     *         "customAssets": ["${file("assets/my-image.png")}"],
+     *         "customStyleSheets": ["${file("assets/my-styles.css")}"],
+     *         "footerMessage": "(c) 2022 MyOrg"
+     *     }
+     *     """
+     *     pluginsMapConfiguration.set(
+     *         mapOf("org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration)
+     *     )
+     * }
+     * ```
+     */
     @Input
-    val failOnWarning: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(DokkaDefaults.failOnWarning)
+    val pluginsMapConfiguration: MapProperty<String, String> = project.objects.mapProperty()
 
+    /**
+     * 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`.
+     * - Synthetic (generated by the compiler) and does not have any documentation, such as
+     *   `dataClass.componentN` or `dataClass.copy`.
+     *
+     * Default is `true`
+     */
     @Input
     val suppressObviousFunctions: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .safeConvention(DokkaDefaults.suppressObviousFunctions)
 
+    /**
+     * Whether to suppress inherited members that aren't explicitly overridden in a given class.
+     *
+     * Note: this can suppress functions such as `equals`/`hashCode`/`toString`, but cannot suppress
+     * synthetic functions such as `dataClass.componentN` and `dataClass.copy`. Use [suppressObviousFunctions]
+     * for that.
+     *
+     * Default is `false`.
+     */
     @Input
     val suppressInheritedMembers: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .safeConvention(DokkaDefaults.suppressInheritedMembers)
 
+    /**
+     * Whether to resolve remote files/links over network.
+     *
+     * This includes package-lists used for generating external documentation links:
+     * for instance, to make classes from standard library clickable.
+     *
+     * Setting this to `true` can significantly speed up build times in certain cases,
+     * but can also worsen documentation quality and user experience, for instance by
+     * not resolving some dependency's class/member links.
+     *
+     * When using offline mode, you can cache fetched files locally and provide them to
+     * Dokka as local paths. For instance, see [GradleExternalDocumentationLinkBuilder].
+     *
+     * Default is `false`.
+     */
     @Input
     val offlineMode: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .safeConvention(DokkaDefaults.offlineMode)
 
-    @Input
-    val pluginsConfiguration: ListProperty<in DokkaConfiguration.PluginConfiguration> = project.objects.listProperty()
-
     /**
-     * Used to keep compatibility with gradle using Kotlin lower than 1.3.50
+     * Whether to fail documentation generation if Dokka has emitted a warning or an error.
+     * Will wait until all errors and warnings have been emitted first.
+     *
+     * This setting works well with [GradleDokkaSourceSetBuilder.reportUndocumented]
+     *
+     * Default is `false`.
      */
     @Input
-    val pluginsMapConfiguration: MapProperty<String, String> = project.objects.mapProperty()
+    val failOnWarning: Property<Boolean> = project.objects.safeProperty<Boolean>()
+        .safeConvention(DokkaDefaults.failOnWarning)
 
+    @Optional
+    @InputDirectory
+    @PathSensitive(PathSensitivity.RELATIVE)
+    val cacheRoot: Property<File?> = project.objects.safeProperty()
+
+    /**
+     * Type-safe configuration for a Dokka plugin.
+     *
+     * Note: this is available in Kotlin DSL only, if Dokka Gradle plugin was applied through `plugins` block
+     * and the configured plugin can be found on classpath, which may require adding a classpath dependency
+     * to `buildscript` block in case of external plugins. Some Dokka plugins, such as
+     * [org.jetbrains.dokka.base.DokkaBase], are on classpath by default.
+     *
+     * Example:
+     *
+     * ```kotlin
+     * import org.jetbrains.dokka.base.DokkaBase
+     * import org.jetbrains.dokka.base.DokkaBaseConfiguration
+     *
+     * tasks.dokkaHtml {
+     *     pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+     *         footerMessage = "Test"
+     *     }
+     * }
+     * ```
+     *
+     * @param P Plugin class that extends [DokkaPlugin]
+     * @param T Plugin configuration class that extends [ConfigurableBlock]
+     */
     inline fun <reified P : DokkaPlugin, reified T : ConfigurableBlock> pluginConfiguration(block: T.() -> Unit) {
         val instance = T::class.createInstance().apply(block)
         val pluginConfiguration = PluginConfigurationImpl(
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt
index 76213f14..c930bc50 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt
@@ -16,6 +16,33 @@ private typealias TaskPath = String
 
 @CacheableTask
 abstract class DokkaMultiModuleTask : AbstractDokkaParentTask() {
+
+    /**
+     * List of Markdown files that contain
+     * [module and package documentation](https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation).
+     *
+     * Contents of specified files will be parsed and embedded into documentation as module and package descriptions.
+     *
+     * Example of such a file:
+     *
+     * ```markdown
+     * # Module kotlin-demo
+     *
+     * The module shows the Dokka usage.
+     *
+     * # Package org.jetbrains.kotlin.demo
+     *
+     * Contains assorted useful stuff.
+     *
+     * ## Level 2 heading
+     *
+     * Text after this heading is also part of documentation for `org.jetbrains.kotlin.demo`
+     *
+     * # Package org.jetbrains.kotlin.demo2
+     *
+     * Useful stuff in another package.
+     * ```
+     */
     @InputFiles
     @Optional
     @PathSensitive(PathSensitivity.RELATIVE)
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaSourceSetMapper.kt
index 56c3f071..56c3f071 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaSourceSetMapper.kt
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt
index 717527d2..6390336a 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt
@@ -13,6 +13,29 @@ import org.jetbrains.dokka.*
 import java.io.File
 import java.net.URL
 
+/**
+ * [Source set](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) level configuration.
+ *
+ * Can be configured in the following way with Gradle Kotlin DSL:
+ *
+ * ```kotlin
+ * import org.jetbrains.dokka.gradle.DokkaTask
+ *
+ * tasks.dokkaHtml {
+ *     dokkaSourceSets {
+ *         // configure individual source set by name
+ *         named("customSourceSet") {
+ *             suppress.set(true)
+ *         }
+ *
+ *         // configure all source sets at once
+ *         configureEach {
+ *             reportUndocumented.set(true)
+ *         }
+ *     }
+ * }
+ * ```
+ */
 open class GradleDokkaSourceSetBuilder(
     @Transient @get:Input val name: String,
     @Transient @get:Internal internal val project: Project,
@@ -22,177 +45,423 @@ open class GradleDokkaSourceSetBuilder(
     @Input
     val sourceSetID: DokkaSourceSetID = sourceSetIdFactory.create(name)
 
+    /**
+     * Whether this source set should be skipped when generating documentation.
+     *
+     * Default is `false`.
+     */
     @Input
     val suppress: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .safeConvention(false)
 
-    @Classpath
-    @Optional
-    val classpath: ConfigurableFileCollection = project.files()
-
+    /**
+     * Display name used to refer to the source set.
+     *
+     * The name will be used both externally (for example, source set name visible to documentation readers) and
+     * internally (for example, for logging messages of [reportUndocumented]).
+     *
+     * By default, the value is deduced from information provided by the Kotlin Gradle plugin.
+     */
     @Input
     @Optional
     val displayName: Property<String?> = project.objects.safeProperty()
 
+    /**
+     * List of Markdown files that contain
+     * [module and package documentation](https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation).
+     *
+     * Contents of specified files will be parsed and embedded into documentation as module and package descriptions.
+     *
+     * Example of such a file:
+     *
+     * ```markdown
+     * # Module kotlin-demo
+     *
+     * The module shows the Dokka usage.
+     *
+     * # Package org.jetbrains.kotlin.demo
+     *
+     * Contains assorted useful stuff.
+     *
+     * ## Level 2 heading
+     *
+     * Text after this heading is also part of documentation for `org.jetbrains.kotlin.demo`
+     *
+     * # Package org.jetbrains.kotlin.demo2
+     *
+     * Useful stuff in another package.
+     * ```
+     */
     @InputFiles
+    @Optional
     @PathSensitive(PathSensitivity.RELATIVE)
-    val sourceRoots: ConfigurableFileCollection = project.objects.fileCollection()
+    val includes: ConfigurableFileCollection = project.files()
+
+    /**
+     * Set of visibility modifiers that should be documented.
+     *
+     * This can be used if you want to document protected/internal/private declarations,
+     * as well as if you want to exclude public declarations and only document internal API.
+     *
+     * Can be configured on per-package basis, see [GradlePackageOptionsBuilder.documentedVisibilities].
+     *
+     * Default is [DokkaConfiguration.Visibility.PUBLIC].
+     */
+    @Input
+    val documentedVisibilities: SetProperty<DokkaConfiguration.Visibility> = project.objects.setProperty<DokkaConfiguration.Visibility>()
+        .convention(DokkaDefaults.documentedVisibilities)
 
+    /**
+     * Specifies source sets that current source set depends on.
+     *
+     * Among other things, this information is needed to resolve
+     * [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html) declarations.
+     *
+     * Prefer using [dependsOn] function to append dependent source sets to this list.
+     *
+     * By default, the values are deduced from information provided by the Kotlin Gradle plugin.
+     */
     @Input
     val dependentSourceSets: SetProperty<DokkaSourceSetID> = project.objects.setProperty<DokkaSourceSetID>()
         .convention(emptySet())
 
-    @InputFiles
+    /**
+     * Classpath for analysis and interactive samples.
+     *
+     * Useful if some types that come from dependencies are not resolved/picked up automatically.
+     * Property accepts both `.jar` and `.klib` files.
+     *
+     * By default, classpath is deduced from information provided by the Kotlin Gradle plugin.
+     */
+    @Classpath
     @Optional
+    val classpath: ConfigurableFileCollection = project.files()
+
+    /**
+     * Source code roots to be analyzed and documented.
+     * Accepts directories and individual `.kt` / `.java` files.
+     *
+     * Prefer using [sourceRoot] function to append source roots to this list.
+     *
+     * By default, source roots are deduced from information provided by the Kotlin Gradle plugin.
+     */
+    @InputFiles
     @PathSensitive(PathSensitivity.RELATIVE)
-    val samples: ConfigurableFileCollection = project.files()
+    val sourceRoots: ConfigurableFileCollection = project.objects.fileCollection()
 
+    /**
+     * List of directories or files that contain sample functions which are referenced via
+     * [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) KDoc tag.
+     */
     @InputFiles
     @Optional
     @PathSensitive(PathSensitivity.RELATIVE)
-    val includes: ConfigurableFileCollection = project.files()
-
-    @Input
-    val includeNonPublic: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(DokkaDefaults.includeNonPublic)
-
-    @Input
-    val documentedVisibilities: SetProperty<DokkaConfiguration.Visibility> = project.objects.setProperty<DokkaConfiguration.Visibility>()
-        .convention(DokkaDefaults.documentedVisibilities)
+    val samples: ConfigurableFileCollection = project.files()
 
+    /**
+     * Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs
+     * after they have been filtered by [documentedVisibilities].
+     *
+     * This setting works well with [AbstractDokkaTask.failOnWarning].
+     *
+     * Can be overridden for a specific package by setting [GradlePackageOptionsBuilder.reportUndocumented].
+     *
+     * Default is `false`.
+     */
     @Input
     val reportUndocumented: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .safeConvention(DokkaDefaults.reportUndocumented)
 
-    @Input
-    val skipEmptyPackages: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(DokkaDefaults.skipEmptyPackages)
-
-    @Input
-    val skipDeprecated: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(DokkaDefaults.skipDeprecated)
-
-    @Input
-    val suppressGeneratedFiles: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(true)
-
-    @Input
-    val jdkVersion: Property<Int> = project.objects.safeProperty<Int>()
-        .safeConvention(DokkaDefaults.jdkVersion)
-
+    /**
+     * Specifies the location of the project source code on the Web. If provided, Dokka generates
+     * "source" links for each declaration. See [GradleSourceLinkBuilder] for more details.
+     *
+     * Prefer using [sourceLink] action/closure for adding source links.
+     */
     @Nested
     val sourceLinks: SetProperty<GradleSourceLinkBuilder> = project.objects.setProperty<GradleSourceLinkBuilder>()
         .convention(emptySet())
 
+    /**
+     * Allows to customize documentation generation options on a per-package basis.
+     *
+     * @see GradlePackageOptionsBuilder for details
+     */
     @Nested
     val perPackageOptions: ListProperty<GradlePackageOptionsBuilder> =
         project.objects.listProperty<GradlePackageOptionsBuilder>()
             .convention(emptyList())
 
+    /**
+     * Allows linking to Dokka/Javadoc documentation of the project's dependencies.
+     *
+     * Prefer using [externalDocumentationLink] action/closure for adding links.
+     */
     @Nested
     val externalDocumentationLinks: SetProperty<GradleExternalDocumentationLinkBuilder> =
         project.objects.setProperty<GradleExternalDocumentationLinkBuilder>()
             .convention(emptySet())
 
+    /**
+     * Platform to be used for setting up code analysis and samples.
+     *
+     * The default value is deduced from information provided by the Kotlin Gradle plugin.
+     */
     @Input
     @Optional
-    val languageVersion: Property<String?> = project.objects.safeProperty()
+    val platform: Property<Platform> = project.objects.safeProperty<Platform>()
+        .safeConvention(Platform.DEFAULT)
 
+    /**
+     * Whether to skip packages that contain no visible declarations after
+     * various filters have been applied.
+     *
+     * For instance, if [skipDeprecated] is set to `true` and your package contains only
+     * deprecated declarations, it will be considered to be empty.
+     *
+     * Default is `true`.
+     */
     @Input
-    @Optional
-    val apiVersion: Property<String?> = project.objects.safeProperty()
+    val skipEmptyPackages: Property<Boolean> = project.objects.safeProperty<Boolean>()
+        .safeConvention(DokkaDefaults.skipEmptyPackages)
 
+    /**
+     * Whether to document declarations annotated with [Deprecated].
+     *
+     * Can be overridden on package level by setting [GradlePackageOptionsBuilder.skipDeprecated].
+     *
+     * Default is `false`.
+     */
+    @Input
+    val skipDeprecated: Property<Boolean> = project.objects.safeProperty<Boolean>()
+        .safeConvention(DokkaDefaults.skipDeprecated)
+
+    /**
+     * Directories or individual files that should be suppressed, meaning declarations from them
+     * will be not documented.
+     *
+     * Will be concatenated with generated files if [suppressGeneratedFiles] is set to `false`.
+     */
+    @InputFiles
+    @PathSensitive(PathSensitivity.RELATIVE)
+    val suppressedFiles: ConfigurableFileCollection = project.files()
+
+    /**
+     * Whether to document/analyze generated files.
+     *
+     * Generated files are expected to be present under `{project}/{buildDir}/generated` directory.
+     * If set to `true`, it effectively adds all files from that directory to [suppressedFiles], so
+     * you can configure it manually.
+     *
+     * Default is `true`.
+     */
+    @Input
+    val suppressGeneratedFiles: Property<Boolean> = project.objects.safeProperty<Boolean>()
+        .safeConvention(DokkaDefaults.suppressGeneratedFiles)
+
+    /**
+     * Whether to generate external documentation links that lead to API reference
+     * documentation for Kotlin's standard library when declarations from it are used.
+     *
+     * Default is `false`, meaning links will be generated.
+     */
     @Input
     val noStdlibLink: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .safeConvention(DokkaDefaults.noStdlibLink)
 
+    /**
+     * Whether to generate external documentation links to JDK's Javadocs
+     * when declarations from it are used.
+     *
+     * The version of JDK Javadocs is determined by [jdkVersion] property.
+     *
+     * Default is `false`, meaning links will be generated.
+     */
     @Input
     val noJdkLink: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .safeConvention(DokkaDefaults.noJdkLink)
 
+    /**
+     * Whether to generate external documentation links for Android SDK API reference
+     * when declarations from it are used.
+     *
+     * Only relevant in Android projects, ignored otherwise.
+     *
+     * Default is `false`, meaning links will be generated.
+     */
     @Input
     val noAndroidSdkLink: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(false)
-
-    @InputFiles
-    @PathSensitive(PathSensitivity.RELATIVE)
-    val suppressedFiles: ConfigurableFileCollection = project.files()
+        .safeConvention(DokkaDefaults.noAndroidSdkLink)
+
+    /**
+     * [Kotlin language version](https://kotlinlang.org/docs/compatibility-modes.html)
+     * used for setting up analysis and [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier)
+     * environment.
+     *
+     * By default, the latest language version available to Dokka's embedded compiler will be used.
+     */
+    @Input
+    @Optional
+    val languageVersion: Property<String?> = project.objects.safeProperty()
 
+    /**
+     * [Kotlin API version](https://kotlinlang.org/docs/compatibility-modes.html)
+     * used for setting up analysis and [@sample](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier)
+     * environment.
+     *
+     * By default, it will be deduced from [languageVersion].
+     */
     @Input
     @Optional
-    val platform: Property<Platform> = project.objects.safeProperty<Platform>()
-        .safeConvention(Platform.DEFAULT)
+    val apiVersion: Property<String?> = project.objects.safeProperty()
+
+    /**
+     * JDK version to use when generating external documentation links for Java types.
+     *
+     * For instance, if you use [java.util.UUID] from JDK in some public declaration signature,
+     * and this property is set to `8`, Dokka will generate an external documentation link
+     * to [JDK 8 Javadocs](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html) for it.
+     *
+     * Default is JDK 8.
+     */
+    @Input
+    val jdkVersion: Property<Int> = project.objects.safeProperty<Int>()
+        .safeConvention(DokkaDefaults.jdkVersion)
+
+    /**
+     * Deprecated. Use [documentedVisibilities] instead.
+     */
+    @Input
+    val includeNonPublic: Property<Boolean> = project.objects.safeProperty<Boolean>()
+        .safeConvention(DokkaDefaults.includeNonPublic)
 
     fun DokkaSourceSetID(sourceSetName: String): DokkaSourceSetID = sourceSetIdFactory.create(sourceSetName)
 
+    /**
+     * Convenient override to **append** source sets to [dependentSourceSets]
+     */
     fun dependsOn(sourceSet: SourceSet) {
         dependsOn(DokkaSourceSetID(sourceSet.name))
     }
 
+    /**
+     * Convenient override to **append** source sets to [dependentSourceSets]
+     */
     fun dependsOn(sourceSet: GradleDokkaSourceSetBuilder) {
         dependsOn(sourceSet.sourceSetID)
     }
 
+    /**
+     * Convenient override to **append** source sets to [dependentSourceSets]
+     */
     fun dependsOn(sourceSet: DokkaConfiguration.DokkaSourceSet) {
         dependsOn(sourceSet.sourceSetID)
     }
 
+    /**
+     * Convenient override to **append** source sets to [dependentSourceSets]
+     */
     fun dependsOn(sourceSetName: String) {
         dependsOn(DokkaSourceSetID(sourceSetName))
     }
 
+    /**
+     * Convenient override to **append** source sets to [dependentSourceSets]
+     */
     fun dependsOn(sourceSetID: DokkaSourceSetID) {
         dependentSourceSets.add(sourceSetID)
     }
 
+    /**
+     * Convenient override to **append** source roots to [sourceRoots]
+     */
     fun sourceRoot(file: File) {
         sourceRoots.from(file)
     }
 
+    /**
+     * Convenient override to **append** source roots to [sourceRoots]
+     */
     fun sourceRoot(path: String) {
         sourceRoot(project.file(path))
     }
 
+    /**
+     * Closure for configuring source links, appending to [sourceLinks].
+     *
+     * @see [GradleSourceLinkBuilder] for details.
+     */
     @Suppress("DEPRECATION") // TODO [beresnev] ConfigureUtil will be removed in Gradle 8
     fun sourceLink(c: Closure<in GradleSourceLinkBuilder>) {
         val configured = org.gradle.util.ConfigureUtil.configure(c, GradleSourceLinkBuilder(project))
         sourceLinks.add(configured)
     }
 
+    /**
+     * Action for configuring source links, appending to [sourceLinks].
+     *
+     * @see [GradleSourceLinkBuilder] for details.
+     */
     fun sourceLink(action: Action<in GradleSourceLinkBuilder>) {
         val sourceLink = GradleSourceLinkBuilder(project)
         action.execute(sourceLink)
         sourceLinks.add(sourceLink)
     }
 
+    /**
+     * Closure for configuring package options, appending to [perPackageOptions].
+     *
+     * @see [GradlePackageOptionsBuilder] for details.
+     */
     @Suppress("DEPRECATION") // TODO [beresnev] ConfigureUtil will be removed in Gradle 8
     fun perPackageOption(c: Closure<in GradlePackageOptionsBuilder>) {
         val configured = org.gradle.util.ConfigureUtil.configure(c, GradlePackageOptionsBuilder(project))
         perPackageOptions.add(configured)
     }
 
+    /**
+     * Action for configuring package options, appending to [perPackageOptions].
+     *
+     * @see [GradlePackageOptionsBuilder] for details.
+     */
     fun perPackageOption(action: Action<in GradlePackageOptionsBuilder>) {
         val option = GradlePackageOptionsBuilder(project)
         action.execute(option)
         perPackageOptions.add(option)
     }
 
+    /**
+     * Closure for configuring external documentation links, appending to [externalDocumentationLinks].
+     *
+     * @see [GradleExternalDocumentationLinkBuilder] for details.
+     */
     @Suppress("DEPRECATION") // TODO [beresnev] ConfigureUtil will be removed in Gradle 8
     fun externalDocumentationLink(c: Closure<in GradleExternalDocumentationLinkBuilder>) {
         val link = org.gradle.util.ConfigureUtil.configure(c, GradleExternalDocumentationLinkBuilder(project))
         externalDocumentationLinks.add(link)
     }
 
+    /**
+     * Action for configuring external documentation links, appending to [externalDocumentationLinks].
+     *
+     * See [GradleExternalDocumentationLinkBuilder] for details.
+     */
     fun externalDocumentationLink(action: Action<in GradleExternalDocumentationLinkBuilder>) {
         val link = GradleExternalDocumentationLinkBuilder(project)
         action.execute(link)
         externalDocumentationLinks.add(link)
     }
 
+    /**
+     * Convenient override to **append** external documentation links to [externalDocumentationLinks].
+     */
     fun externalDocumentationLink(url: String, packageListUrl: String? = null) {
         externalDocumentationLink(URL(url), packageListUrl = packageListUrl?.let(::URL))
     }
 
+    /**
+     * Convenient override to **append** external documentation links to [externalDocumentationLinks].
+     */
     fun externalDocumentationLink(url: URL, packageListUrl: URL? = null) {
         externalDocumentationLinks.add(
             GradleExternalDocumentationLinkBuilder(project).apply {
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderExtensions.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderExtensions.kt
index c5c7428f..5c7c523b 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderExtensions.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderExtensions.kt
@@ -3,14 +3,23 @@ package org.jetbrains.dokka.gradle
 import com.android.build.gradle.api.AndroidSourceSet
 import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
 
+/**
+ * Convenient override to **append** source sets to [GradleDokkaSourceSetBuilder.dependentSourceSets]
+ */
 fun GradleDokkaSourceSetBuilder.dependsOn(sourceSet: KotlinSourceSet) {
     dependsOn(DokkaSourceSetID(sourceSet.name))
 }
 
+/**
+ * Convenient override to **append** source sets to [GradleDokkaSourceSetBuilder.dependentSourceSets]
+ */
 fun GradleDokkaSourceSetBuilder.dependsOn(sourceSet: AndroidSourceSet) {
     dependsOn(DokkaSourceSetID(sourceSet.name))
 }
 
+/**
+ * Extension allowing configuration of Dokka source sets via Kotlin Gradle plugin source sets.
+ */
 fun GradleDokkaSourceSetBuilder.kotlinSourceSet(kotlinSourceSet: KotlinSourceSet) {
     configureWithKotlinSourceSet(kotlinSourceSet)
 }
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleExternalDocumentationLinkBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleExternalDocumentationLinkBuilder.kt
index 19d150c3..36e4f81d 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleExternalDocumentationLinkBuilder.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleExternalDocumentationLinkBuilder.kt
@@ -10,12 +10,60 @@ import org.jetbrains.dokka.ExternalDocumentationLink
 import org.jetbrains.dokka.ExternalDocumentationLinkImpl
 import java.net.URL
 
+/**
+ * Configuration builder that allows creating links leading to externally hosted
+ * documentation of your dependencies.
+ *
+ * For instance, if you are using types from `kotlinx.serialization`, by default
+ * they will be unclickable in your documentation, as if unresolved. However,
+ * since API reference for `kotlinx.serialization` is also built by Dokka and is
+ * [published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/),
+ * you can configure external documentation links for it, allowing Dokka to generate
+ * documentation links for used types, making them clickable and appear resolved.
+ *
+ * Example in Gradle Kotlin DSL:
+ *
+ * ```kotlin
+ * externalDocumentationLink {
+ *     url.set(URL("https://kotlinlang.org/api/kotlinx.serialization/"))
+ *     packageListUrl.set(
+ *         rootProject.projectDir.resolve("serialization.package.list").toURL()
+ *     )
+ * }
+ * ```
+ */
 class GradleExternalDocumentationLinkBuilder(
     @Transient @get:Internal internal val project: Project
 ) : DokkaConfigurationBuilder<ExternalDocumentationLinkImpl> {
+
+    /**
+     * Root URL of documentation to link with. **Must** contain a trailing slash.
+     *
+     * Dokka will do its best to automatically find `package-list` for the given URL, and link
+     * declarations together.
+     *
+     * It automatic resolution fails or if you want to use locally cached files instead,
+     * consider providing [packageListUrl].
+     *
+     * Example:
+     *
+     * ```kotlin
+     * java.net.URL("https://kotlinlang.org/api/kotlinx.serialization/")
+     * ```
+     */
     @Input
     val url: Property<URL?> = project.objects.safeProperty()
 
+    /**
+     * Specifies the exact location of a `package-list` instead of relying on Dokka
+     * automatically resolving it. Can also be a locally cached file to avoid network calls.
+     *
+     * Example:
+     *
+     * ```kotlin
+     * rootProject.projectDir.resolve("serialization.package.list").toURL()
+     * ```
+     */
     @Optional
     @Input
     val packageListUrl: Property<URL?> = project.objects.safeProperty()
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt
index f15a6462..4e53cf81 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt
@@ -13,33 +13,91 @@ import org.jetbrains.dokka.DokkaConfigurationBuilder
 import org.jetbrains.dokka.DokkaDefaults
 import org.jetbrains.dokka.PackageOptionsImpl
 
-
+/**
+ * Configuration builder that allows setting some options for specific packages
+ * matched by [matchingRegex].
+ *
+ * Example in Gradle Kotlin DSL:
+ *
+ * ```kotlin
+ * tasks.dokkaHtml {
+ *     dokkaSourceSets.configureEach {
+ *         perPackageOption {
+ *             matchingRegex.set(".*internal.*")
+ *             suppress.set(true)
+ *         }
+ *     }
+ * }
+ * ```
+ */
 class GradlePackageOptionsBuilder(
     @Transient @get:Internal internal val project: Project
 ) : DokkaConfigurationBuilder<PackageOptionsImpl> {
+
+    /**
+     * Regular expression that is used to match the package.
+     *
+     * Default is any string: `.*`.
+     */
     @Input
     val matchingRegex: Property<String> = project.objects.safeProperty<String>()
         .safeConvention(".*")
 
+    /**
+     * Whether this package should be skipped when generating documentation.
+     *
+     * Default is `false`.
+     */
     @Input
-    val includeNonPublic: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(DokkaDefaults.includeNonPublic)
+    val suppress: Property<Boolean> = project.objects.safeProperty<Boolean>()
+        .safeConvention(DokkaDefaults.suppress)
 
+    /**
+     * Set of visibility modifiers that should be documented.
+     *
+     * This can be used if you want to document protected/internal/private declarations within a
+     * specific package, as well as if you want to exclude public declarations and only document internal API.
+     *
+     * Can be configured for a whole source set, see [GradleDokkaSourceSetBuilder.documentedVisibilities].
+     *
+     * Default is [DokkaConfiguration.Visibility.PUBLIC].
+     */
     @Input
     val documentedVisibilities: SetProperty<DokkaConfiguration.Visibility> = project.objects.setProperty<DokkaConfiguration.Visibility>()
         .convention(DokkaDefaults.documentedVisibilities)
 
+    /**
+     * Whether to document declarations annotated with [Deprecated].
+     *
+     * Can be overridden on source set level by setting [GradleDokkaSourceSetBuilder.skipDeprecated].
+     *
+     * Default is `false`.
+     */
+    @Input
+    val skipDeprecated: Property<Boolean> = project.objects.safeProperty<Boolean>()
+        .safeConvention(DokkaDefaults.skipDeprecated)
+
+    /**
+     * Whether to emit warnings about visible undocumented declarations, that is declarations from
+     * this package and without KDocs, after they have been filtered by [documentedVisibilities].
+     *
+     * This setting works well with [AbstractDokkaTask.failOnWarning].
+     *
+     * Can be overridden on source set level by setting [GradleDokkaSourceSetBuilder.reportUndocumented].
+     *
+     * Default is `false`.
+     */
     @Input
     val reportUndocumented: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .safeConvention(DokkaDefaults.reportUndocumented)
 
+    /**
+     * Deprecated. Use [documentedVisibilities] instead.
+     */
     @Input
-    val skipDeprecated: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(DokkaDefaults.skipDeprecated)
+    val includeNonPublic: Property<Boolean> = project.objects.safeProperty<Boolean>()
+        .safeConvention(DokkaDefaults.includeNonPublic)
 
-    @Input
-    val suppress: Property<Boolean> = project.objects.safeProperty<Boolean>()
-        .safeConvention(DokkaDefaults.suppress)
 
     override fun build(): PackageOptionsImpl = PackageOptionsImpl(
         matchingRegex = checkNotNull(matchingRegex.getSafe()) { "prefix not specified" },
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt
index 2ddd8056..4a0c1333 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt
@@ -8,17 +8,67 @@ import org.jetbrains.dokka.SourceLinkDefinitionImpl
 import java.io.File
 import java.net.URL
 
+/**
+ * Configuration builder that allows adding a `source` link to each signature
+ * which leads to [remoteUrl] with a specific line number (configurable by setting [remoteLineSuffix]),
+ * letting documentation readers find source code for each declaration.
+ *
+ * Example in Gradle Kotlin DSL:
+ *
+ * ```kotlin
+ * sourceLink {
+ *     localDirectory.set(projectDir.resolve("src"))
+ *     remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
+ *     remoteLineSuffix.set("#L")
+ * }
+ * ```
+ */
 class GradleSourceLinkBuilder(
     @Transient @get:Internal internal val project: Project
 ) : DokkaConfigurationBuilder<SourceLinkDefinitionImpl> {
 
+    /**
+     * Path to the local source directory. The path must be relative to the root of current project.
+     *
+     * Example:
+     *
+     * ```kotlin
+     * projectDir.resolve("src")
+     * ```
+     */
     @InputDirectory
     @PathSensitive(PathSensitivity.RELATIVE)
     val localDirectory: Property<File?> = project.objects.safeProperty()
 
+    /**
+     * URL of source code hosting service that can be accessed by documentation readers,
+     * like GitHub, GitLab, Bitbucket, etc. This URL will be used to generate
+     * source code links of declarations.
+     *
+     * Example:
+     *
+     * ```kotlin
+     * java.net.URL("https://github.com/username/projectname/tree/master/src"))
+     * ```
+     */
     @Input
     val remoteUrl: Property<URL?> = project.objects.safeProperty()
 
+    /**
+     * Suffix used to append source code line number to the URL. This will help readers navigate
+     * not only to the file, but to the specific line number of the declaration.
+     *
+     * The number itself will be appended to the specified suffix. For instance,
+     * if this property is set to `#L` and the line number is 10, resulting URL suffix
+     * will be `#L10`
+     *
+     * Suffixes used by popular services:
+     * - GitHub: `#L`
+     * - GitLab: `#L`
+     * - Bitbucket: `#lines-`
+     *
+     * Default is `#L`.
+     */
     @Optional
     @Input
     val remoteLineSuffix: Property<String> = project.objects.safeProperty<String>()