Revise documentation (#2728)

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

3 files changed, 32 insertions, 58 deletions

diff --git a/core/src/main/kotlin/DokkaBootstrapImpl.kt b/core/src/main/kotlin/DokkaBootstrapImpl.kt
index 75c4c0af..114bade7 100644
--- a/core/src/main/kotlin/DokkaBootstrapImpl.kt
+++ b/core/src/main/kotlin/DokkaBootstrapImpl.kt
@@ -1,45 +1,9 @@
 package org.jetbrains.dokka
 
-import org.jetbrains.dokka.DokkaConfiguration.PackageOptions
 import org.jetbrains.dokka.utilities.DokkaLogger
 
 import java.util.function.BiConsumer
 
-
-fun parsePerPackageOptions(args: List<String>): List<PackageOptions> = args.map { it.split(",") }.map {
-    val matchingRegex = it.first()
-
-    val options = it.subList(1, it.size)
-
-    val deprecated = options.find { it.endsWith("skipDeprecated") }?.startsWith("+")
-        ?: DokkaDefaults.skipDeprecated
-
-    val reportUndocumented = options.find { it.endsWith("reportUndocumented") }?.startsWith("+")
-        ?: DokkaDefaults.reportUndocumented
-
-    val privateApi = options.find { it.endsWith("includeNonPublic") }?.startsWith("+")
-        ?: DokkaDefaults.includeNonPublic
-
-    val suppress = options.find { it.endsWith("suppress") }?.startsWith("+")
-        ?: DokkaDefaults.suppress
-
-    val documentedVisibilities = options
-        .filter { it.matches(Regex("\\+visibility:.+")) } // matches '+visibility:' with at least one symbol after the semicolon
-        .map { DokkaConfiguration.Visibility.fromString(it.split(":")[1]) }
-        .toSet()
-        .ifEmpty { DokkaDefaults.documentedVisibilities }
-
-    PackageOptionsImpl(
-        matchingRegex,
-        includeNonPublic = privateApi,
-        documentedVisibilities = documentedVisibilities,
-        reportUndocumented = reportUndocumented,
-        skipDeprecated = !deprecated,
-        suppress = suppress
-    )
-}
-
-
 /**
  * Accessed with reflection
  */
diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt
index c26faf28..77384ace 100644
--- a/core/src/main/kotlin/configuration.kt
+++ b/core/src/main/kotlin/configuration.kt
@@ -12,30 +12,38 @@ import java.net.URL
 
 object DokkaDefaults {
     val moduleName: String = "root"
+    val moduleVersion: String? = null
     val outputDir = File("./dokka")
-    const val format: String = "html"
-    val cacheRoot: File? = null
-    const val offlineMode: Boolean = false
     const val failOnWarning: Boolean = false
-    const val delayTemplateSubstitution: Boolean = false
+    const val suppressObviousFunctions = true
+    const val suppressInheritedMembers = false
+    const val offlineMode: Boolean = false
+
+    const val sourceSetDisplayName = "JVM"
+    const val sourceSetName = "main"
+    val analysisPlatform: Platform = Platform.DEFAULT
+
+    const val suppress: Boolean = false
+    const val suppressGeneratedFiles: Boolean = true
 
-    const val includeNonPublic: Boolean = false
-    val documentedVisibilities: Set<DokkaConfiguration.Visibility> = setOf(DokkaConfiguration.Visibility.PUBLIC)
-    const val reportUndocumented: Boolean = false
     const val skipEmptyPackages: Boolean = true
     const val skipDeprecated: Boolean = false
-    const val jdkVersion: Int = 8
+
+    const val reportUndocumented: Boolean = false
+
     const val noStdlibLink: Boolean = false
+    const val noAndroidSdkLink: Boolean = false
     const val noJdkLink: Boolean = false
-    val analysisPlatform: Platform = Platform.DEFAULT
-    const val suppress: Boolean = false
+    const val jdkVersion: Int = 8
+
+    const val includeNonPublic: Boolean = false
+    val documentedVisibilities: Set<DokkaConfiguration.Visibility> = setOf(DokkaConfiguration.Visibility.PUBLIC)
 
-    const val sourceSetDisplayName = "JVM"
-    const val sourceSetName = "main"
-    val moduleVersion: String? = null
     val pluginsConfiguration = mutableListOf<PluginConfigurationImpl>()
-    const val suppressObviousFunctions = true
-    const val suppressInheritedMembers = false
+
+    const val delayTemplateSubstitution: Boolean = false
+
+    val cacheRoot: File? = null
 }
 
 enum class Platform(val key: String) {
@@ -88,10 +96,12 @@ data class DokkaSourceSetID(
 fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(json)
 
 /**
- * Global options are applied to all packages and modules and overwrite package configuration.
+ * Global options can be configured and applied to all packages and modules at once, overwriting package configuration.
+ *
+ * These are handy if we have multiple source sets sharing the same global options as it reduces the size of the
+ * boilerplate. Otherwise, the user would be forced to repeat all these options for each source set.
  *
- * These are handy if we have multiple sourcesets sharing the same global options as it reduces the size of the boilerplate.
- * Otherwise, the user would be enforced to repeat all these options per each sourceset.
+ * @see [apply] to learn how to apply global configuration
  */
 data class GlobalDokkaConfiguration(
     val perPackageOptions: List<PackageOptionsImpl>?,
diff --git a/core/src/main/kotlin/defaultConfiguration.kt b/core/src/main/kotlin/defaultConfiguration.kt
index 8c7c8b5d..66154570 100644
--- a/core/src/main/kotlin/defaultConfiguration.kt
+++ b/core/src/main/kotlin/defaultConfiguration.kt
@@ -71,9 +71,9 @@ data class SourceLinkDefinitionImpl(
         fun parseSourceLinkDefinition(srcLink: String): SourceLinkDefinitionImpl {
             val (path, urlAndLine) = srcLink.split('=')
             return SourceLinkDefinitionImpl(
-                File(path).canonicalPath,
-                URL(urlAndLine.substringBefore("#")),
-                urlAndLine.substringAfter("#", "").let { if (it.isEmpty()) null else "#$it" })
+                localDirectory = File(path).canonicalPath,
+                remoteUrl = URL(urlAndLine.substringBefore("#")),
+                remoteLineSuffix = urlAndLine.substringAfter("#", "").let { if (it.isEmpty()) null else "#$it" })
         }
     }
 }
@@ -85,7 +85,7 @@ data class PackageOptionsImpl(
     override val reportUndocumented: Boolean?,
     override val skipDeprecated: Boolean,
     override val suppress: Boolean,
-    override val documentedVisibilities: Set<DokkaConfiguration.Visibility>,
+    override val documentedVisibilities: Set<DokkaConfiguration.Visibility>, // TODO add default to DokkaDefaults.documentedVisibilities
 ) : DokkaConfiguration.PackageOptions