Revise documentation (#2728)

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

4 files changed, 448 insertions, 54 deletions

diff --git a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt
index 581d4c9e..92ab9754 100644
--- a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt
+++ b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt
@@ -24,28 +24,6 @@ import org.jetbrains.dokka.DokkaConfiguration.ExternalDocumentationLink
 import java.io.File
 import java.net.URL
 
-class SourceLinkMapItem {
-    @Parameter(name = "path", required = true)
-    var path: String = ""
-
-    @Parameter(name = "url", required = true)
-    var url: String = ""
-
-    @Parameter(name = "lineSuffix")
-    var lineSuffix: String? = null
-}
-
-class ExternalDocumentationLinkBuilder {
-
-    @Parameter(name = "url", required = true)
-    var url: URL? = null
-
-    @Parameter(name = "packageListUrl", required = true)
-    var packageListUrl: URL? = null
-
-    fun build() = ExternalDocumentationLink(url, packageListUrl)
-}
-
 abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List<Dependency>) : AbstractMojo() {
 
     @Parameter(defaultValue = "\${project}", readonly = true, required = true)
@@ -64,118 +42,303 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List<Dependenc
     @Component
     private var resolutionErrorHandler: ResolutionErrorHandler? = null
 
-    class PackageOptions : DokkaConfiguration.PackageOptions {
-        @Parameter
-        override var matchingRegex: String = ".*"
-
-        @Parameter
-        @Deprecated("Use [documentedVisibilities] property for a more flexible control over documented visibilities")
-        override var includeNonPublic: Boolean = DokkaDefaults.includeNonPublic
-
-        @Parameter
-        override var reportUndocumented: Boolean = DokkaDefaults.reportUndocumented
-
-        @Parameter
-        override var skipDeprecated: Boolean = DokkaDefaults.skipDeprecated
-
-        @Parameter
-        override var suppress: Boolean = DokkaDefaults.suppress
-
-        @Parameter(property = "visibility")
-        override var documentedVisibilities: Set<DokkaConfiguration.Visibility> = DokkaDefaults.documentedVisibilities
-    }
+    @Parameter(defaultValue = "JVM")
+    var displayName: String = "JVM"
 
     @Parameter
     var sourceSetName: String = "JVM"
 
+    /**
+     * Source code roots to be analyzed and documented.
+     * Accepts directories and individual `.kt` / `.java` files.
+     *
+     * Default is `{project.compileSourceRoots}`.
+     */
     @Parameter(required = true, defaultValue = "\${project.compileSourceRoots}")
     var sourceDirectories: List<String> = emptyList()
 
+    /**
+     * 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.
+     */
     @Parameter
     var samples: List<String> = emptyList()
 
+    /**
+     * 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.
+     * ```
+     */
     @Parameter
     var includes: List<String> = emptyList()
 
+    /**
+     * 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.
+     *
+     * Default is `{project.compileClasspathElements}`.
+     */
     @Parameter(required = true, defaultValue = "\${project.compileClasspathElements}")
     var classpath: List<String> = emptyList()
 
+    /**
+     * Specifies the location of the project source code on the Web. If provided, Dokka generates
+     * "source" links for each declaration. See [SourceLinkMapItem] for more details.
+     */
     @Parameter
     var sourceLinks: List<SourceLinkMapItem> = emptyList()
 
+    /**
+     * Display name used to refer to the project/module. Used for ToC, navigation, logging, etc.
+     *
+     * Default is `{project.artifactId}`.
+     */
     @Parameter(required = true, defaultValue = "\${project.artifactId}")
     var moduleName: String = ""
 
+    /**
+     * Whether to skip documentation generation.
+     *
+     * Default is `false`.
+     */
     @Parameter(required = false, defaultValue = "false")
     var skip: Boolean = false
 
+    /**
+     * 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.
+     */
     @Parameter(required = false, defaultValue = "${DokkaDefaults.jdkVersion}")
     var jdkVersion: Int = DokkaDefaults.jdkVersion
 
+    /**
+     * Whether to document declarations annotated with [Deprecated].
+     *
+     * Can be overridden on package level by setting [PackageOptions.skipDeprecated].
+     *
+     * Default is `false`.
+     */
     @Parameter
     var skipDeprecated: Boolean = DokkaDefaults.skipDeprecated
 
+    /**
+     * 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`.
+     */
     @Parameter
     var skipEmptyPackages: Boolean = DokkaDefaults.skipEmptyPackages
 
+    /**
+     * 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 [failOnWarning].
+     *
+     * Can be overridden for a specific package by setting [PackageOptions.reportUndocumented].
+     *
+     * Default is `false`.
+     */
     @Parameter
     var reportUndocumented: Boolean = DokkaDefaults.reportUndocumented
 
+    /**
+     * Allows to customize documentation generation options on a per-package basis.
+     *
+     * @see PackageOptions for details
+     */
     @Parameter
     var perPackageOptions: List<PackageOptions> = emptyList()
 
+    /**
+     * Allows linking to Dokka/Javadoc documentation of the project's dependencies.
+     *
+     * @see ExternalDocumentationLinkBuilder for details
+     */
     @Parameter
     var externalDocumentationLinks: List<ExternalDocumentationLinkBuilder> = emptyList()
 
+    /**
+     * 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.
+     */
     @Parameter(defaultValue = "${DokkaDefaults.noStdlibLink}")
     var noStdlibLink: Boolean = 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.
+     */
     @Parameter(defaultValue = "${DokkaDefaults.noJdkLink}")
     var noJdkLink: Boolean = DokkaDefaults.noJdkLink
 
-    @Parameter
-    var cacheRoot: String? = null
-
-    @Parameter(defaultValue = "JVM")
-    var displayName: String = "JVM"
-
+    /**
+     * 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 [ExternalDocumentationLinkBuilder].
+     *
+     * Default is `false`.
+     */
     @Parameter(defaultValue = "${DokkaDefaults.offlineMode}")
     var offlineMode: Boolean = DokkaDefaults.offlineMode
 
+    /**
+     * [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.
+     */
     @Parameter
     var languageVersion: String? = null
 
+    /**
+     * [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].
+     */
     @Parameter
     var apiVersion: String? = null
 
+    /**
+     * Directories or individual files that should be suppressed, meaning declarations from them
+     * will be not documented.
+     */
     @Parameter
     var suppressedFiles: List<String> = emptyList()
 
-    @Parameter
-    var platform: String = ""
-
-    @Parameter
-    var includeNonPublic: Boolean = DokkaDefaults.includeNonPublic
-
+    /**
+     * 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 [PackageOptions.documentedVisibilities].
+     *
+     * Default is [DokkaConfiguration.Visibility.PUBLIC].
+     */
     @Parameter(property = "visibility")
     var documentedVisibilities: Set<DokkaConfiguration.Visibility> = DokkaDefaults.documentedVisibilities
         // hack to set the default value for lists, didn't find any other safe way
         // maven seems to overwrite Kotlin's default initialization value, so it doesn't matter what you put there
         get() = field.ifEmpty { DokkaDefaults.documentedVisibilities }
 
+    /**
+     * 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 [reportUndocumented]
+     *
+     * Default is `false`.
+     */
     @Parameter
     var failOnWarning: Boolean = DokkaDefaults.failOnWarning
 
+    /**
+     * 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`
+     */
     @Parameter(defaultValue = "${DokkaDefaults.suppressObviousFunctions}")
     var suppressObviousFunctions: Boolean = 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`.
+     */
     @Parameter(defaultValue = "${DokkaDefaults.suppressInheritedMembers}")
     var suppressInheritedMembers: Boolean = DokkaDefaults.suppressInheritedMembers
 
+    /**
+     * Dokka plugins to be using during documentation generation.
+     *
+     * Example:
+     *
+     * ```xml
+     * <dokkaPlugins>
+     *     <plugin>
+     *         <groupId>org.jetbrains.dokka</groupId>
+     *         <artifactId>gfm-plugin</artifactId>
+     *         <version>1.7.20</version>
+     *     </plugin>
+     * </dokkaPlugins>
+     * ```
+     */
     @Parameter
     var dokkaPlugins: List<Dependency> = emptyList()
         get() = field + defaultDokkaPlugins
 
+    @Parameter
+    var cacheRoot: String? = null
+
+    @Parameter
+    var platform: String = ""
+
+    /**
+     * Deprecated. Use [documentedVisibilities] instead.
+     */
+    @Parameter
+    var includeNonPublic: Boolean = DokkaDefaults.includeNonPublic
+
     protected abstract fun getOutDir(): String
 
     override fun execute() {
@@ -320,6 +483,12 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List<Dependenc
     requiresProject = true
 )
 class DokkaMojo : AbstractDokkaMojo(emptyList()) {
+
+    /**
+     * Directory to which documentation will be generated.
+     *
+     * Default is `{project.basedir}/target/dokka`.
+     */
     @Parameter(required = true, defaultValue = "\${project.basedir}/target/dokka")
     var outputDir: String = ""
 
@@ -334,6 +503,12 @@ class DokkaMojo : AbstractDokkaMojo(emptyList()) {
     requiresProject = true
 )
 class DokkaJavadocMojo : AbstractDokkaMojo(listOf(javadocDependency)) {
+
+    /**
+     * Directory to which documentation will be generated.
+     *
+     * Default is `{project.basedir}/target/dokkaJavadoc`.
+     */
     @Parameter(required = true, defaultValue = "\${project.basedir}/target/dokkaJavadoc")
     var outputDir: String = ""
 
@@ -348,6 +523,12 @@ class DokkaJavadocMojo : AbstractDokkaMojo(listOf(javadocDependency)) {
     requiresProject = true
 )
 class DokkaJavadocJarMojo : AbstractDokkaMojo(listOf(javadocDependency)) {
+
+    /**
+     * Directory to which documentation jar will be generated.
+     *
+     * Default is `{project.basedir}/target/dokkaJavadocJar`.
+     */
     @Parameter(required = true, defaultValue = "\${project.basedir}/target/dokkaJavadocJar")
     var outputDir: String = ""
 
diff --git a/runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt b/runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt
new file mode 100644
index 00000000..8e145fd5
--- /dev/null
+++ b/runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt
@@ -0,0 +1,63 @@
+package org.jetbrains.dokka.maven
+
+import org.apache.maven.plugins.annotations.Parameter
+import org.jetbrains.dokka.ExternalDocumentationLink
+import java.net.URL
+
+/**
+ * Configuration block 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:
+ *
+ * ```xml
+ * <externalDocumentationLinks>
+ *     <link>
+ *         <url>https://kotlinlang.org/api/latest/jvm/stdlib/</url>
+ *         <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl>
+ *     </link>
+ * </externalDocumentationLinks>
+ * ```
+ */
+class ExternalDocumentationLinkBuilder {
+
+    /**
+     * 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:
+     *
+     * ```xml
+     * <url>https://kotlinlang.org/api/latest/jvm/stdlib/</url>
+     * ```
+     */
+    @Parameter(name = "url", required = true)
+    var url: URL? = null
+
+    /**
+     * 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:
+     *
+     * ```xml
+     * <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl>
+     * ```
+     */
+    @Parameter(name = "packageListUrl", required = true)
+    var packageListUrl: URL? = null
+
+    fun build() = ExternalDocumentationLink(url, packageListUrl)
+}
diff --git a/runners/maven-plugin/src/main/kotlin/PackageOptions.kt b/runners/maven-plugin/src/main/kotlin/PackageOptions.kt
new file mode 100644
index 00000000..af678769
--- /dev/null
+++ b/runners/maven-plugin/src/main/kotlin/PackageOptions.kt
@@ -0,0 +1,85 @@
+package org.jetbrains.dokka.maven
+
+import org.apache.maven.plugins.annotations.Parameter
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaDefaults
+
+/**
+ * Configuration block that allows setting some options for specific packages
+ * matched by [matchingRegex].
+ *
+ * Example:
+ *
+ * ```xml
+ * <configuration>
+ *     <perPackageOptions>
+ *         <packageOptions>
+ *             <matchingRegex>.*api.*</matchingRegex>
+ *             <suppress>false</suppress>
+ *             <reportUndocumented>false</reportUndocumented>
+ *             <skipDeprecated>false</skipDeprecated>
+ *             <documentedVisibilities>
+ *                 <visibility>PUBLIC</visibility>
+ *                 <visibility>PROTECTED</visibility>
+ *             </documentedVisibilities>
+ *         </packageOptions>
+ *     </perPackageOptions>
+ * </configuration>
+ * ```
+ */
+class PackageOptions : DokkaConfiguration.PackageOptions {
+
+    /**
+     * Regular expression that is used to match the package.
+     *
+     * If multiple packages match the same `matchingRegex`, the longest `matchingRegex` will be used.
+     *
+     * Default is any string: `.*`.
+     */
+    @Parameter
+    override var matchingRegex: String = ".*"
+
+    /**
+     * Whether this package should be skipped when generating documentation.
+     *
+     * Default is `false`.
+     */
+    @Parameter
+    override var suppress: Boolean = DokkaDefaults.suppress
+
+    /**
+     * List 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.
+     *
+     * Default is [DokkaConfiguration.Visibility.PUBLIC].
+     */
+    @Parameter(property = "visibility")
+    override var documentedVisibilities: Set<DokkaConfiguration.Visibility> = DokkaDefaults.documentedVisibilities
+
+    /**
+     * Whether to document declarations annotated with [Deprecated].
+     *
+     * Can be set on project level with [AbstractDokkaMojo.skipDeprecated].
+     *
+     * Default is `false`.
+     */
+    @Parameter
+    override var skipDeprecated: Boolean = 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 [AbstractDokkaMojo.failOnWarning].
+     *
+     * Default is `false`.
+     */
+    @Parameter
+    override var reportUndocumented: Boolean = DokkaDefaults.reportUndocumented
+
+    @Parameter
+    @Deprecated("Use [documentedVisibilities] property for a more flexible control over documented visibilities")
+    override var includeNonPublic: Boolean = DokkaDefaults.includeNonPublic
+}
diff --git a/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt b/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt
new file mode 100644
index 00000000..621b38d8
--- /dev/null
+++ b/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt
@@ -0,0 +1,65 @@
+package org.jetbrains.dokka.maven
+
+import org.apache.maven.plugins.annotations.Parameter
+
+/**
+ * Configuration block that allows adding a `source` link to each signature
+ * which leads to [path] with a specific line number (configurable by setting [lineSuffix]),
+ * letting documentation readers find source code for each declaration.
+ *
+ * Example:
+ *
+ * ```xml
+ * <sourceLinks>
+ *     <link>
+ *         <path>${project.basedir}/src</path>
+ *         <url>https://github.com/kotlin/dokka/tree/master/src</url>
+ *         <lineSuffix>#L</lineSuffix>
+ *     </link>
+ * </sourceLinks>
+ * ```
+ */
+class SourceLinkMapItem {
+
+    /**
+     * Path to the local source directory. The path must be relative to the root of current project.
+     *
+     * Example:
+     *
+     * ```xml
+     * <path>${project.basedir}/src</path>
+     * ```
+     */
+    @Parameter(name = "path", required = true)
+    var path: String = ""
+
+    /**
+     * 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:
+     *
+     * ```xml
+     * <url>https://github.com/username/projectname/tree/master/src</url>
+     * ```
+     */
+    @Parameter(name = "url", required = true)
+    var url: String = ""
+
+    /**
+     * 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-`
+     */
+    @Parameter(name = "lineSuffix")
+    var lineSuffix: String? = null
+}