Revise documentation (#2728)

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

1 files changed, 235 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 = ""