Proofread developer guides

docs/src/doc/docs/community/plugins-list.md

@@ -1,14 +1,20 @@
 # Dokka community plugins
 
-TODO add a link on how to apply plugins
+On this page you can find `Dokka` plugins which are supported by both `Dokka` maintainers and community members.
+
+If you want to add your plugin to this list, get in touch with maintainers via [Slack](../community/slack.md)
+or `GitHub`.
+
+If you want to learn how to develop plugins for `Dokka`, see 
+[Plugin development](../developer_guide/plugin-development/introduction.md) section.
 
 ## Output Formats
 
 ### Javadoc (Alpha)
 
 Javadoc plugin adds a `Javadoc` output format that looks like Java's `Javadoc`, but it's for the most part
 a lookalike, so you may experience problems if you try to use it with a tool that expects native
-`Javadocs` generated by `Java`.
+`Javadoc` documentation generated by `Java`.
 
 `Javadoc` plugin does not support multiplatform projects and does not have a multi-module task.
 
@@ -26,7 +32,7 @@ a lookalike, so you may experience problems if you try to use it with a tool tha
 
 ### GFM (Alpha)
 
-`GFM` plugins adds an ability to generate documentation in `GitHub flavoured Markdown` format. Supports both
+`GFM` plugins adds the ability to generate documentation in `GitHub flavoured Markdown` format. Supports both
 multimodule and multiplatform projects, and is shipped together with `Dokka`, so you can start using it
 right away with one of the following tasks:
 
@@ -40,26 +46,26 @@ ___
 
 //[dokka-debug-kts](#gfm)/[org.jetbrains.dokka.test](#gfm)/[MyClass](#gfm)
 
-# MyClass
+#### MyClass
 
 [jvm]
 class [MyClass](#gfm)
 
 KDoc that describes this class
 
-## Constructors
+##### Constructors
 
 | | |
 |---|---|
 | [MyClass](#gfm) | [jvm]<br>fun [MyClass](#gfm)() |
 
-## Functions
+##### Functions
 
 | Name             | Summary |
 |------------------|---|
 | [function](#gfm) | [jvm]<br>fun [function](#gfm)(): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment on top of this function |
 
-## Properties
+##### Properties
 
 | Name | Summary                                                                                                                                        |
 |---|------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -74,7 +80,7 @@ ___
 
 ### Jekyll (Alpha)
 
-`Jekyll` plugins adds an ability to generate documentation in `Jekyll flavoured Markdown` format. Supports both
+`Jekyll` plugins adds the ability to generate documentation in `Jekyll flavoured Markdown` format. Supports both
 multi-module and multiplatform projects, and is shipped together with `Dokka`, so you can start using it
 right away with one of the following tasks:
 
@@ -91,18 +97,18 @@ right away with one of the following tasks:
 
 ### Mathjax
 
-[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `Dokka` `MathJax` plugin
-adds an ability to render mathematics from source code comments.
+[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `MathJax` plugin
+adds the ability to render mathematics from source code comments.
 
-If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` 2.7.6 with `config=TeX-AMS_SVG`
+If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` (ver. 2) with `config=TeX-AMS_SVG`
 to generated `HTML` pages.
 
 Usage example:
 ```kotlin
 /**
- * @usesMathJax
- *
  * Some math \(\sqrt{3x-1}+(1+x)^2\)
+ * 
+ * @usesMathJax
  */
 class Foo {}
 ```
@@ -118,6 +124,26 @@ Which results in:
 [Mermaid JS](https://mermaid-js.github.io/mermaid/#/) lets you create diagrams and visualizations using text and code. 
 `Mermaid` plugin allows rendering such diagrams and visualizations found in source code documentation.
 
+Usage example:
+```kotlin
+/**
+ * See the graph for more details:
+ * \```mermaid
+ * graph LR
+ *   A[Christmas] -->|Get money| B(Go shopping)
+ *   B --> C{Let me think}
+ *   C -->|One| D[Laptop]
+ *   C -->|Two| E[iPhone]
+ *   C -->|Three| F[fa:fa-car Car]
+ * \```
+ */
+class CompositeSubscription
+```
+
+Which results in:
+
+![Mermaid demo](../images/mermaid_demo.png){ width="700" }
+
 For more information and examples, see 
 [Html Mermaid Dokka plugin](https://github.com/glureau/dokka-mermaid) repository on GitHub.
 

docs/src/doc/docs/community/slack.md

@@ -1,7 +1,7 @@
 # Slack channel
 
-Dokka has a dedicated `#dokka` channel in the Kotlin Community Slack, where you can ask questions and chat 
-about using, customizing or contributing to Dokka. 
+`Dokka` has a dedicated `#dokka` channel in the `Kotlin Community Slack`, where you can ask questions and chat 
+about using, customizing or contributing to `Dokka`. 
 
 [Follow the instructions](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up)
 to get an invite or [connect directly](https://kotlinlang.slack.com). 

docs/src/doc/docs/developer_guide/architecture/architecture_overview.md

@@ -1,21 +1,23 @@
 # Architecture overview
 
-Normally, you would think that a tool like Dokka simply parses some programming language sources and generates
+Normally, you would think that a tool like `Dokka` simply parses some programming language sources and generates
 `HTML` pages for whatever it sees along the way, with little to no abstractions. That would be the simplest and
 shortest way to implement a documentation engine.
 
-However, it was clear that Dokka may need to generate documentation from various sources (not only `Kotlin`), that users
+However, it was clear that `Dokka` may need to generate documentation from various sources (not only `Kotlin`), that users
 might request additional output formats (like `Markdown`), that users might need additional features like supporting
-custom KDoc tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside
-Dokka itself if all solutions were hardcoded.
+custom `KDoc` tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside
+`Dokka` itself if all solutions were hardcoded.
 
-For this reason, Dokka was built from the ground up to be extensible and customizable. You can think of the general
-flow of generating documentation with Dokka as mapping one intermediate representation / abstraction into another.
-You, as a Dokka developer or a plugin writer, can use extension points and introduce selective changes to the
-model on any level without touching everything else.
+For this reason, `Dokka` was built from the ground up to be extensible and customizable. You can think of the general
+flow of generating documentation with `Dokka` as mapping one intermediate representation / abstraction into another.
+You, as a `Dokka` developer or a plugin writer, can use extension points and introduce selective changes to the
+model on one particular level without touching the rest.
 
 ## Overview of data model
 
+Below you can find the general flow and transformation of Dokka's models.
+
 ```mermaid
 flowchart TD
     Input --> Documentables --> Documentables --> Pages --> Pages --> Output
@@ -25,9 +27,13 @@ flowchart TD
 * `Documentables` - unified data model that represents any parsed sources as a tree. 
   Examples: class/function/package/property
 * `Pages` - universal model that represents pages (e.g a function/property page) and its content
-  (lists, text, code blocks) that the users needs to see
-* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of content to
+  (lists, text, code blocks) that the users needs to see. Not to be confused with `.html` pages. Goes hand in hand
+  with so-called Content Model.
+* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of pages/content model to
   some human-readable and visual representation. For instance:
+    * `PageNode` is mapped as 
+        * `.html` file for `HTML` format
+        * `.md` file for `Markdown` format
     * `ContentList` is mapped as
         * `<li>` / `<ul>` for `HTML` format
         * `1.` / `*` for `Markdown` format
@@ -63,7 +69,7 @@ class MyPlugin : DokkaPlugin() {
         signatureProvider with KotlinSignatureProvider()
     }
 
-    // register our own extension in another plugin and override its default
+    // register our own extension in base plugin and override its default
     val dokkaBasePlugin by lazy { plugin<DokkaBase>() }
     val multimoduleLocationProvider by extending {
         (dokkaBasePlugin.locationProviderFactory
@@ -74,6 +80,7 @@ class MyPlugin : DokkaPlugin() {
 
 // use a registered extention, pretty much dependency injection
 class MyExtension(val context: DokkaContext) {
+
     val signatureProvider: SignatureProvider = context.plugin<MyPlugin>().querySingle { signatureProvider }
 
     fun doSomething() {

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

@@ -1,7 +1,7 @@
-# Documentables
+# Documentables Model
 
-Documentables represent data that is parsed from some sources. Think of this data model as of something that could be
-seen or produced by a compiler frontend, and it's not far off from the truth.
+Documentables represent data that is parsed from sources. Think of this data model as of something that could be
+seen or produced by a compiler frontend, it's not far off from the truth.
 
 By default, documentables are parsed from `Descriptor` (for `Kotlin`)
 and [Psi](https://plugins.jetbrains.com/docs/intellij/psi.html)
@@ -67,23 +67,23 @@ data class DClass(
 
 ___
 
-There are three non-documentable classes important for this model:
+There are three non-documentable classes that important for this model:
 
 * `DRI`
 * `SourceSetDependent`
 * `ExtraProperty`.
 
 ### DRI
 
-`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies specific `Documentable`.
+`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies a specific `Documentable`.
 All references and relations between documentables (other than direct ownership) are described using `DRI`.
 
 For example, `DFunction` with a parameter of type `Foo` has only `Foo`'s `DRI`, not the actual reference
 to `Foo`'s `Documentable` object.
 
 #### Example
 
-For an example of how a `DRI` can look like, let's look at `limitedParallelism` function from `kotlinx.coroutines`:
+For an example of how a `DRI` can look like, let's take the `limitedParallelism` function from `kotlinx.coroutines`:
 
 ```kotlin
 package kotlinx.coroutines
@@ -152,22 +152,54 @@ ___
 
 ## Documentation model
 
-Documentation model is used along `Documentable` model to store data obtained by parsing
+Documentation model is used alongside Documentables to store data obtained by parsing
 code comments (such as `KDoc`/`Javadoc`).
 
 ### DocTag
 
-`DocTag` describes a specific documentation syntax element, universal across source languages. For instance,
-DocTag `B` is the same for `**bold**` in `Kotlin` and `<b>bold</b>` in `Java`.
+`DocTag` describes a specific documentation syntax element.
 
-However, some `DocTag` elements are specific to a certain language, there are many such example for `Java`
-because it allows HTML tags inside `Javadoc` comments, some of which are not possible with `Markdown`.
+It's universal across source languages. For instance, DocTag `B` is the same for `**bold**` in `Kotlin` and
+`<b>bold</b>` in `Java`.
+
+However, some `DocTag` elements are specific to a certain language, there are many such examples for `Java`
+because it allows HTML tags inside `Javadoc` comments, some of which are simply not possible to reproduce with `Markdown`.
 
 `DocTag` elements can be deeply nested with other `DocTag` children elements.
 
+Examples:
+
+```kotlin
+data class H1(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : DocTag()
+
+data class H2(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : DocTag()
+
+data class Strikethrough(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : DocTag()
+
+data class Strong(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : DocTag()
+
+data class CodeBlock(
+    override val children: List<DocTag> = emptyList(),
+    override val params: Map<String, String> = emptyMap()
+) : Code()
+
+```
+
 ### TagWrapper
 
-`TagWrapper` described a whole comment description or a specific comment tag.
+`TagWrapper` describes the whole comment description or a specific comment tag.
 For example: `@see` / `@author` / `@return`.
 
 Since each such section may contain formatted text inside of it, each `TagWrapper` has `DocTag` children.

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

@@ -2,7 +2,10 @@
 
 ## Introduction
 
-`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md) models.
+`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md#content-model)
+models.
+
+Source code for `ExtraProperty`:
 
 ```kotlin
 interface ExtraProperty<in C : Any> {
@@ -21,6 +24,7 @@ when declaring new extras:
 
 ```kotlin
 data class CustomExtra(
+    [any data relevant to your extra], 
     [any data relevant to your extra] 
 ): ExtraProperty<Documentable> {
     override val key: CustomExtra.Key<Documentable, *> = CustomExtra
@@ -51,7 +55,7 @@ which can only be stored in a specific `Documentable`.
 
 ## Usage example
 
-In following example we will create `DFunction`-only property, store it and then retrieve its value:
+In following example we will create a `DFunction`-only property, store it and then retrieve its value:
 
 ```kotlin
 data class CustomExtra(val customExtraValue: String) : ExtraProperty<DFunction> {

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

@@ -9,7 +9,7 @@ Page model represents the structure of documentation pages to be generated. Duri
 is processed separately, so one page corresponds to exactly one output file.
 
 Page model is independent of the final output format, in other words it's universal. Which extension the pages
-should be created as (`.html`, `.md`, etc) and how is up to the `Renderer` part.
+should be created as (`.html`, `.md`, etc) and how is up to the `Renderer`.
 
 Subclasses of `PageNode` represent different kinds of rendered pages, such as `ModulePage`, `PackagePage`,
 `ClasslikePage`, `MemberPage` (properties, functions), etc.
@@ -28,7 +28,7 @@ flowchart TD
     firstPackageClasslike --> firstPackageClasslikeSecondMember[MemberPageNode - Property]
 ```
 
-Almost all pages are `ContentPage` - it's the type of `Page` that has `Content` on it.
+Almost all pages are derivatives of `ContentPage` - it's the type of `Page` that has `Content` on it.
 
 ## Content Model
 
@@ -44,7 +44,7 @@ to wrap all children with some style.
 // real example of composing content using `DocumentableContentBuilder` DSL
 orderedList {
     item {
-        text("The following table is nested in a list:")
+        text("This list contains a nested table:")
         table {
             header {
                 text("Col1")
@@ -61,16 +61,17 @@ orderedList {
 }
 ```
 
-It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. For instance,
-`HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might render it using
-backticks.
+It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. 
+
+For instance, `HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might 
+render it using backticks.
 
 ___
 
 ### DCI
 
 Each node is identified by unique `DCI`, which stands for _Dokka Content Identifier_. `DCI` aggregates `DRI`s of all
-`Documentables` that make up specific `ContentNode`.
+`Documentables` that make up a specific `ContentNode`.
 
 ```kotlin
 data class DCI(val dri: Set<DRI>, val kind: Kind)

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

@@ -1,10 +1,11 @@
 # Base extensions
 
-`DokkaBase` is a base plugin which defines a number of default implementations for `CoreExtensions` as well as declares
-its own, more high-level, extension points to be used from other plugins and output formats.
+`DokkaBase` class is a base plugin which defines a number of default implementations for `CoreExtensions` as well as
+declares its own, more high-level extension points to be used from other plugins and output formats.
 
 It's very convenient to use extension points and defaults defined in `DokkaBase` if you have an idea for a simple
-plugin that only needs to provide a few extensions or change a single place and have everything else be the default.
+plugin that only needs to provide a few extensions or change a single extension point and have everything else be the
+default.
 
 `DokkaBase` is used extensively for Dokka's own output formats such as `HTML`, `Markdown`, `Mathjax` and others.