Address code review points

buildSrc/src/main/kotlin/org/jetbrains/publication.kt

@@ -100,7 +100,7 @@ fun Project.configureSonatypePublicationIfNecessary(vararg publications: String)
 fun MavenPublication.configurePom(projectName: String) {
     pom {
         name.set(projectName)
-        description.set("Dokka is a documentation engine for Kotlin and Java, performing the same function as Javadoc for Java")
+        description.set("Dokka is an API documentation engine for Kotlin and Java, performing the same function as Javadoc for Java")
         url.set("https://github.com/Kotlin/dokka")
 
         licenses {

docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md

@@ -12,6 +12,8 @@ and [Psi](https://plugins.jetbrains.com/docs/intellij/psi.html)
 
 Upon creation, it's a collection of trees, each with `DModule` as root.
 
+Here's an example of how an arbitrary `Documentable` tree might look like:
+
 ```mermaid
 flowchart TD
     DModule --> firstPackage[DPackage]
@@ -128,7 +130,8 @@ kotlinx.coroutines/MainCoroutineDispatcher/limitedParallelism/#kotlin.Int/Pointi
 ### SourceSetDependent
 
 `SourceSetDependent` helps handling multiplatform data by associating platform-specific data (declared with either
-`expect` or `actual` modifier) with particular source sets.
+`expect` or `actual` modifier) with particular 
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets).
 
 This comes in handy if `expect`/`actual` declarations differ. For instance, the default value for `actual` might differ
 from that declared in `expect`, or code comments written for `expect` might be different from what's written

docs/src/doc/docs/developer_guide/architecture/data_model/extra.md

@@ -32,8 +32,10 @@ data class CustomExtra(
 }
 ```
 
-Merge strategy for extras is invoked only if merged objects have different values for same Extra.
-If you don't expect it to happen, you can omit implementing `mergeStrategyFor` function.
+Merge strategy (`mergeStrategyFor` method) for extras is invoked during
+[merging](../extension_points/core_extensions.md#documentablemerger) if documentables from different 
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) each
+have their own `Extra`. 
 
 ## PropertyContainer
 

docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md

@@ -16,6 +16,8 @@ Subclasses of `PageNode` represent different kinds of rendered pages, such as `M
 
 The Page Model is a tree structure, with `RootPageNode` at the root.
 
+Here's an example of how an arbitrary `Page` tree might look like:
+
 ```mermaid
 flowchart TD
     RootPageNode --> firstPackage[PackagePageNode]

docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md

@@ -28,7 +28,8 @@ On this page we'll go over each extension point individually.
 `PreGenerationChecker` can be used to run some checks and constraints. 
 
 For instance, `Javadoc` plugin does not support generating documentation for multi-platform projects, so it uses
-`PreGenerationChecker` to check for multi-platform source sets and fails if it finds any.
+`PreGenerationChecker` to check for multi-platform
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and fails if it finds any.
 
 ## Generation
 
@@ -87,7 +88,8 @@ you can either introduce a similar extension point or rely on [DocumentableTrans
 will be discussed below.
 
 `PreMergeDocumentableTransformer` allows applying any transformation to 
-[Documentables model](../data_model/documentables.md) before different source sets are merged. 
+[Documentables model](../data_model/documentables.md) before different 
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) are merged. 
 
 Useful if you want to filter/map existing documentables. For instance, if you want to exclude members annotated with
 `@Internal`, you most likely need an implementation of `PreMergeDocumentableTransformer`.
@@ -105,8 +107,9 @@ requires one function to be overridden. The rest is taken care of.
 `DocumentableTransformer` performs the same function as `PreMergeDocumentableTransformer`, but after merging source
 sets.
 
-Notable example is `InheritorsExtractorTransformer`, it extracts inherited classes data across source sets
-and creates an inheritance map.
+Notable example is `InheritorsExtractorTransformer`, it extracts inherited classes data across 
+[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and creates an inheritance
+map.
 
 #### DocumentableToPageTranslator
 

docs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md

@@ -276,7 +276,8 @@ otherwise it will fail.
 Things to note and remember:
 
 1. Your test class should extend `BaseAbstractTest`, which contains base utility methods for testing.
-2. You can configure Dokka to your liking, enable some specific settings, configure source sets, etc. All done via
+2. You can configure Dokka to your liking, enable some specific settings, configure 
+   [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets), etc. All done via
    `dokkaConfiguration` DSL.
 3. `testInline` function is the main entry point for unit tests
 4. You can pass plugins to be used in a test, notice `pluginOverrides` parameter

docs/src/doc/docs/index.md

@@ -5,8 +5,9 @@ but it's modern and highly pluggable.
 
 Just like `Kotlin` itself, `Dokka` supports mixed-language projects (`Kotlin`/`Java`). It understands
 [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in `Kotlin` source files as well
-as `Javadoc` comments in `Java` files, and can generate documentation in multiple formats including its
-own `HTML` format, Java's `Javadoc` lookalike and `Markdown`.
+as [Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#format) in `Java` 
+files, and can generate documentation in multiple formats including its own `HTML` format, Java's `Javadoc` lookalike
+and `Markdown`.
 
 Some libraries that use `Dokka` for API reference docs:
 
@@ -27,8 +28,8 @@ ___
 
 `Dokka` is also very pluggable and comes with convenient plugin and extension point API. 
 
-You can write a plugin to support [mermaid.js](https://mermaid-js.github.io/mermaid/#/) diagrams,
-[mathjax](https://www.mathjax.org/) formulas or even write custom processing of your own tags and annotations.
+You can write a plugin to support [mermaid.js](community/plugins-list.md#mermaid) diagrams,
+[mathjax](community/plugins-list.md#mathjax) formulas or even write custom processing of your own tags and annotations.
 
 For more info, see:
 

docs/src/doc/docs/user_guide/applying/gradle.md

@@ -1,8 +1,9 @@
 # Using the Gradle plugin
 
 !!! important
-If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our
-[migration guide](https://github.com/Kotlin/dokka/blob/master/runners/gradle-plugin/MIGRATION.md)
+
+    If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our
+    [migration guide](https://github.com/Kotlin/dokka/blob/master/runners/gradle-plugin/MIGRATION.md)
 
 ### Supported versions
 Dokka should work on gradle newer than 5.6

docs/src/doc/mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: Dokka documentation
 
 # Meta tags (placed in header)
-site_description: Dokka is a documentation engine for Kotlin, performing the same function as the Javadoc tool for Java
+site_description: Dokka is an API documentation engine for Kotlin, performing the same function as the Javadoc tool for Java
 site_author: JetBrains
 site_url: https://github.com/Kotlin/dokka