Add descriptions for configuration options

core/api/core.api

@@ -57,10 +57,6 @@ public final class org/jetbrains/dokka/DokkaBootstrapImpl$DokkaProxyLogger : org
 	public fun warn (Ljava/lang/String;)V
 }
 
-public final class org/jetbrains/dokka/DokkaBootstrapImplKt {
-	public static final fun parsePerPackageOptions (Ljava/util/List;)Ljava/util/List;
-}
-
 public abstract interface class org/jetbrains/dokka/DokkaConfiguration : java/io/Serializable {
 	public abstract fun getCacheRoot ()Ljava/io/File;
 	public abstract fun getDelayTemplateSubstitution ()Z
@@ -215,6 +211,7 @@ public final class org/jetbrains/dokka/DokkaDefaults {
 	public static final field format Ljava/lang/String;
 	public static final field includeNonPublic Z
 	public static final field jdkVersion I
+	public static final field noAndroidSdkLink Z
 	public static final field noJdkLink Z
 	public static final field noStdlibLink Z
 	public static final field offlineMode Z
@@ -224,6 +221,7 @@ public final class org/jetbrains/dokka/DokkaDefaults {
 	public static final field sourceSetDisplayName Ljava/lang/String;
 	public static final field sourceSetName Ljava/lang/String;
 	public static final field suppress Z
+	public static final field suppressGeneratedFiles Z
 	public static final field suppressInheritedMembers Z
 	public static final field suppressObviousFunctions Z
 	public final fun getAnalysisPlatform ()Lorg/jetbrains/dokka/Platform;
@@ -365,6 +363,7 @@ public final class org/jetbrains/dokka/GlobalDokkaConfiguration {
 
 public final class org/jetbrains/dokka/PackageOptionsImpl : org/jetbrains/dokka/DokkaConfiguration$PackageOptions {
 	public fun <init> (Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;)V
+	public synthetic fun <init> (Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Ljava/lang/String;
 	public final fun component2 ()Z
 	public final fun component3 ()Ljava/lang/Boolean;

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
  */

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>?,

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
 
 

docs/topics/formats/html.md

@@ -22,7 +22,8 @@ This format comes standard in all runners:
 
 ## Configuration
 
-HTML format is Dokka's base format, so it is configurable through `DokkaBase` and `DokkaBaseConfiguration`:
+HTML format is Dokka's base format, so it is configurable through `DokkaBase` and `DokkaBaseConfiguration`
+classes:
 
 <tabs group="build-script">
 <tab title="Kotlin" group-key="kotlin">
@@ -160,7 +161,7 @@ Via [JSON configuration](cli.md#running-with-json-configuration):
 </tab>
 </tabs>
 
-For details, see [configuring Dokka plugins](plugins_introduction.md#configuring-dokka-plugins) section.
+For more details, see [configuring Dokka plugins](plugins_introduction.md#configuring-dokka-plugins) topic.
 
 ### Configuration options
 
@@ -176,7 +177,7 @@ For details, see [configuring Dokka plugins](plugins_introduction.md#configuring
 
 ## Customization
 
-HTML format is highly customizable to the point where you wouldn't be able to tell it was generated by Dokka.
+HTML format provides a number of customization options.
 
 ### Customizing styles
 
@@ -192,7 +193,7 @@ Files with the same name will be overwritten, so it is possible to override styl
 | `prism.css`          | Styles for [PrismJS](https://prismjs.com/) syntax highlighter |
 | `jetbrains-mono.css` | Font styling                                                  |
 
-All of these are 
+Source code for all of the used styles is 
 [available on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/styles).
 
 ### Customizing assets
@@ -203,18 +204,18 @@ You can provide your own images to be bundled with documentation by setting `cus
 Files with the same name will be overwritten, so it is possible to override images and icons that Dokka uses. The most
 useful and relevant one being `logo-icon.svg`, which is the image that's used in the header. The rest is mostly icons.
 
-You can view all images used by Dokka on 
+You can find all images used by Dokka on 
 [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/images).
 
 ### Changing the logo
 
 To customize the logo, you can begin by [providing your own asset](#customizing-assets) for `logo-icon.svg`. If your
 image has similar size, it should not look out of place.
 
-However, if your image has different dimensions or you want to use a `.png` image instead of the default `.svg`,
-you can [override `logo-styles.css` stylesheet](#customizing-styles).  
+However, if your image has different dimensions or you want to use a `.png` image instead of the default `.svg` file,
+you can [override `logo-styles.css` stylesheet](#customizing-styles) and make it fit.  
 
-For more details, see 
+For an example of how to do it, see 
 [custom format example project](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle/dokka-customFormat-example).
 
 ### Modifying footer
@@ -226,7 +227,7 @@ You can modify the footer message by setting `footerMessage` [configuration prop
 Dokka provides the ability to modify [FreeMarker](https://freemarker.apache.org/) templates used for generating 
 documentation pages.
 
-You can completely change the header, add your own banners/menus/search, load analytics, change body styling and so on.
+You can change the header completely, add your own banners/menus/search, load analytics, change body styling and so on.
 
 Dokka uses the following templates:
 
@@ -238,7 +239,7 @@ Dokka uses the following templates:
 | `includes/page_metadata.ft`       | Metadata used within `<head>` container.                                                                          |
 | `includes/source_set_selector.ft` | [Source set](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) selector in the header. |
 
-`base.ftl` template is the base template and it includes all the other ones. You can find all templates 
+`base.ftl` template is the base template and it includes all the other ones. You can find source code for all templates 
 [on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/templates).
 
 You can override any template by setting `templatesDir` [configuration property](#configuration). Dokka will look
@@ -268,11 +269,11 @@ context and thus need to be resolved at later stages by the [MultiModule](gradle
 
 #### Directives
 
-Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html) can also be used:
+You can also use the following Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html):
 
-| **Variable** | **Description**                                                                                                                        |
-|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
-| `<@content/>`              | Main page content.                                                                                                                     |
-| `<@resources/>`            | Resources such as scripts and stylesheets.                                                                                             |
-| `<@version/>`              | Module version taken from configuration. If [versioning plugin](versioning.md) is applied, it will be replaced with version navigator. |
+| **Variable**    | **Description**                                                                                                                        |
+|-----------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| `<@content/>`   | Main page content.                                                                                                                     |
+| `<@resources/>` | Resources such as scripts and stylesheets.                                                                                             |
+| `<@version/>`   | Module version taken from configuration. If [versioning plugin](versioning.md) is applied, it will be replaced with version navigator. |
 

docs/topics/formats/markdown.md

@@ -10,7 +10,7 @@ These formats give you more freedom in terms of hosting documentation as the out
 documentation website. For example, see [OkHttp's API reference](https://square.github.io/okhttp/4.x/okhttp/okhttp3/)
 pages.
 
-Markdown output formats are rendering [Dokka plugin](plugins_introduction.md), maintained by the Dokka team, and 
+Markdown output formats are rendering [Dokka plugins](plugins_introduction.md), maintained by the Dokka team, and 
 they are open source.
 
 ## GFM

docs/topics/overview.md

@@ -111,3 +111,8 @@ Learn more about Maven configuration in a separate [topic dedicated to Maven](ma
 
 </tab>
 </tabs>
+
+## Community
+
+Dokka has a dedicated `#dokka` channel in [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up)
+where you can chat about Dokka itself, its plugins and how to develop them, and get in touch with maintainers.

docs/topics/plugins/plugins_introduction.md

@@ -17,12 +17,14 @@ Dokka plugins are published as separate artifacts, so to apply a Dokka plugin yo
 From there, the plugin will extend Dokka by itself - no extra actions needed. 
 
 > Plugins that use the same extension points or work in a similar way can interfere with each other.
-> This may lead to visual bugs, general undefined behaviour or even failed builds. If you notice anything of that
-> nature, it's a good idea to check which plugins are applied and what they do.
+> This may lead to visual bugs, general undefined behaviour or even failed builds. However, it should not lead to 
+> concurrency issues since Dokka does not expose any mutable data structures or objects.
+> 
+> If you notice any problems of such nature, it's a good idea to check which plugins are applied and what they do.
 > 
 {type="note"}
 
-Let's have a look at how you can apply [mathjax plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax)
+Let's have a look at how you can apply the [mathjax plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax)
 to your project:
 
 <tabs group="build-script">
@@ -125,7 +127,7 @@ If you are using [JSON configuration](cli.md#running-with-json-configuration), D
 
 ## Configuring Dokka plugins
 
-Dokka plugins can also have configuration options of their own. Consult plugin's documentation to see which
+Dokka plugins can also have configuration options of their own. Consult used plugin's documentation to see which
 options are available.
 
 Let's have a look at how you can configure `DokkaBase` plugin, which is responsible for generating [HTML](html.md)