diff options
Diffstat (limited to 'docs')
47 files changed, 4076 insertions, 2795 deletions
diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..686c95bd --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Dokka documentation + +This folder contains the Dokka documentation that is available on [kotlinlang.org](https://kotlinlang.org/). + +Our documentation is written in Markdown format with some domain specific language (DSL) constructs that are used at +JetBrains. + +If you wish to contribute to the documentation, please read through +[Kotlin documentation guidelines](https://docs.google.com/document/d/1mUuxK4xwzs3jtDGoJ5_zwYLaSEl13g_SuhODdFuh2Dc/edit). diff --git a/docs/build.gradle.kts b/docs/build.gradle.kts deleted file mode 100644 index 1a93d550..00000000 --- a/docs/build.gradle.kts +++ /dev/null @@ -1,3 +0,0 @@ -plugins { - id("ru.vyarus.mkdocs") version "2.3.0" -} diff --git a/docs/cfg/buildprofiles.xml b/docs/cfg/buildprofiles.xml new file mode 100644 index 00000000..86c3ad59 --- /dev/null +++ b/docs/cfg/buildprofiles.xml @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<buildprofiles> + <variables> + <enable-browser-edits>true</enable-browser-edits> + <browser-edits-url>https://github.com/Kotlin/dokka/edit/master/docs/</browser-edits-url> + <allow-indexable-eaps>true</allow-indexable-eaps> + </variables> + <build-profile product="kl"/> +</buildprofiles> diff --git a/docs/dokka.tree b/docs/dokka.tree new file mode 100644 index 00000000..73ac277e --- /dev/null +++ b/docs/dokka.tree @@ -0,0 +1,24 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE product-profile + SYSTEM "https://resources.jetbrains.com/stardust/product-profile.dtd"> + +<product-profile id="kl" + name="dokka" + start-page="dokka-introduction.md"> + + <chunk include-id="dokka"> + <toc-element id="dokka-introduction.md"/> + <toc-element id="dokka-get-started.md"/> + <toc-element toc-title="Run Dokka"> + <toc-element id="dokka-gradle.md"/> + <toc-element id="dokka-maven.md"/> + <toc-element id="dokka-cli.md"/> + </toc-element> + <toc-element toc-title="Output formats"> + <toc-element id="dokka-html.md"/> + <toc-element id="dokka-markdown.md"/> + <toc-element id="dokka-javadoc.md"/> + </toc-element> + <toc-element id="dokka-plugins.md"/> + </chunk> +</product-profile> diff --git a/docs/images/dokkaHtmlCollector-example.png b/docs/images/dokkaHtmlCollector-example.png Binary files differnew file mode 100644 index 00000000..5bd74d8d --- /dev/null +++ b/docs/images/dokkaHtmlCollector-example.png diff --git a/docs/images/dokkaHtmlMultiModule-example.png b/docs/images/dokkaHtmlMultiModule-example.png Binary files differnew file mode 100644 index 00000000..f5091f56 --- /dev/null +++ b/docs/images/dokkaHtmlMultiModule-example.png diff --git a/docs/images/javadoc-format-example.png b/docs/images/javadoc-format-example.png Binary files differnew file mode 100644 index 00000000..45ac585c --- /dev/null +++ b/docs/images/javadoc-format-example.png diff --git a/docs/images/versioning-plugin-example.png b/docs/images/versioning-plugin-example.png Binary files differnew file mode 100644 index 00000000..cd02c558 --- /dev/null +++ b/docs/images/versioning-plugin-example.png diff --git a/docs/project.ihp b/docs/project.ihp new file mode 100644 index 00000000..f9ab9b9e --- /dev/null +++ b/docs/project.ihp @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/stardust/ihp.dtd"> + +<ihp version="2.0"> +<!-- <categories src="categories.list"/>--> + <module name="dokka"/> + <topics dir="topics"/> + <images dir="images"/> + <vars src="vars.list"/> + <product src="dokka.tree" version="%dokkaVersion%" /> + <settings> + <default-property element-name="toc-element" property-name="show-structure-depth" value="2"/> + </settings> +</ihp> diff --git a/docs/src/doc/docs/community/plugins-list.md b/docs/src/doc/docs/community/plugins-list.md deleted file mode 100644 index 6ae8ce4c..00000000 --- a/docs/src/doc/docs/community/plugins-list.md +++ /dev/null @@ -1,160 +0,0 @@ -# Dokka community 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 -`Javadoc` documentation generated by `Java`. - -`Javadoc` plugin does not support multiplatform projects and does not have a multi-module task. - -`Javadoc` plugin is shipped with `Dokka`, so you can start using it right away with one of the following tasks: - -* `dokkaJavadoc` - builds `Javadoc` documentation for single-module projects or for a specific module. -* `dokkaJavadocCollector` - collects generated `Javadoc` documentation from submodules and assembles it together. - -`Javadoc` plugin has its own signature provider that essentially translates `Kotlin` signatures to `Java` ones. - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc) - -### GFM (Alpha) - -`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: - -* `dokkaGfm` - generate documentation for a non multi-module project or one specific module. -* `dokkaGfmMultiModule` - generate documentation for a multi-module project, assemble it together and - generate navigation page/menu for all the modules. - -Example: - -___ - -//[dokka-debug-kts](#gfm)/[org.jetbrains.dokka.test](#gfm)/[MyClass](#gfm) - -#### MyClass - -[jvm] -class [MyClass](#gfm) - -KDoc that describes this class - -##### Constructors - -| | | -|---|---| -| [MyClass](#gfm) | [jvm]<br>fun [MyClass](#gfm)() | - -##### 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 - -| Name | Summary | -|---|------------------------------------------------------------------------------------------------------------------------------------------------| -| [property](#gfm) | [jvm]<br>val [property](#gfm): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)<br>KDoc comment for a property | - -___ - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/gfm) - -### Jekyll (Alpha) - -`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: - -* `dokkaJekyll` - generate documentation for a non multi-module project or one specific module. -* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and - generate navigation page/menu for all the modules. - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll) - -## Extensions - -### Mathjax - -[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` (ver. 2) with `config=TeX-AMS_SVG` -to generated `HTML` pages. - -Usage example: -```kotlin -/** - * Some math \(\sqrt{3x-1}+(1+x)^2\) - * - * @usesMathJax - */ -class Foo {} -``` - -Which results in: - -{ width="400" } - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) - -### Mermaid - -[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: - -{ width="700" } - -For more information and examples, see -[Html Mermaid Dokka plugin](https://github.com/glureau/dokka-mermaid) repository on GitHub. - -### Kotlin as Java - -With `Kotlin as Java` plugin applied, all `Kotlin` signatures will be rendered as `Java` signatures. - -For instance, `fun foo(bar: Bar): Baz` will be rendered as `public final Baz foo(Bar bar)`. - -`Kotlin as Java` plugin is published to maven central as a -[separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin): -`org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20`. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) diff --git a/docs/src/doc/docs/community/slack.md b/docs/src/doc/docs/community/slack.md deleted file mode 100644 index 290d4a18..00000000 --- a/docs/src/doc/docs/community/slack.md +++ /dev/null @@ -1,7 +0,0 @@ -# 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`. - -[Follow the instructions](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) -to get an invite or [connect directly](https://kotlinlang.slack.com). diff --git a/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md b/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md deleted file mode 100644 index fb11f32a..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md +++ /dev/null @@ -1,123 +0,0 @@ -# Architecture overview - -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 an API documentation engine. - -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. - -For this reason, `Dokka` was built from the ground up to be easily extensible and customizable by adding several layers -of abstractions to the data model, and by providing pluggable extension points, giving you the ability to introduce -selective changes on a single level. - -## Overview of data model - -Generating API documentation begins with `Input` source files (`.kts`, `.java`, etc) and ends with some `Output` files -(`.html`/`.md` pages, etc). However, to allow for extensibility and customization, several input and output independent -abstractions have been added to the data model. - -Below you can find the general pipeline of processing data gathered from sources and the explanation for each stage. - -```mermaid -flowchart TD - Input --> Documentables --> Pages --> Output -``` - -* `Input` - generalization of sources, by default `Kotlin`/`Java` sources, but could be virtually anything -* `Documentables` - unified data model that represents _any_ parsed sources as a tree, independent of the source - language. Examples of a `Documentable`: class, function, package, property, etc -* `Pages` - universal model that represents output pages (e.g a function/property page) and the content it's composed of - (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 - * `ContentCodeBlock` is mapped as - * `<code>` or `<pre>` with some CSS styles in `HTML` format - * Text wrapped in triple backticks for `Markdown` format - - -You, as a `Dokka` developer or a plugin writer, can use extension points to introduce selective changes to the -model on one particular level without touching everything else. - -For instance, if you wanted to make some annotation/function/class invisible in the final documentation, you would only -need to modify the `Documentables` model by filtering undesirable members out. If you wanted to display all overloaded -methods on the same page instead of on separate ones, you would only need to modify the `Page` model by merging multiple -pages into one, and so on. - -For a deeper dive into Dokka's model with more examples and details, -see sections about [Documentables](data_model/documentables.md) and [Page/Content](data_model/page_content.md) - -For an overview of existing extension points that let you transform Dokka's models, see -[Core extension points](extension_points/core_extensions.md) and [Base extensions](extension_points/base_extensions.md). - -## Overview of extension points - -An extension point usually represents some pluggable interface that performs an action during one of the stages of -generating documentation. An extension is therefore an implementation of that interface which is extending the -extension point. - -You can create extension points, provide your own implementations (extensions) and configure them. All of -this is possible with Dokka's plugin/extension point API. - -Here's a sneak peek of the DSL: - -```kotlin -class MyPlugin : DokkaPlugin() { - // create an extension point for other developers - val signatureProvider by extensionPoint<SignatureProvider>() - - // provide a default implementation - val defaultSignatureProvider by extending { - signatureProvider with KotlinSignatureProvider() - } - - // register our own extension in base plugin and override its default - val dokkaBasePlugin by lazy { plugin<DokkaBase>() } - val multimoduleLocationProvider by extending { - (dokkaBasePlugin.locationProviderFactory - providing MultimoduleLocationProvider::Factory - override dokkaBasePlugin.locationProvider) - } -} - -// use a registered extention, pretty much dependency injection -class MyExtension(val context: DokkaContext) { - - val signatureProvider: SignatureProvider = context.plugin<MyPlugin>().querySingle { signatureProvider } - - fun doSomething() { - signatureProvider.signature(..) - } -} - -interface SignatureProvider { - fun signature(documentable: Documentable): List<ContentNode> -} - -class KotlinSignatureProvider : SignatureProvider { - override fun signature(documentable: Documentable): List<ContentNode> = listOf() -} -``` - -For a deeper dive into extensions and extension points with more examples and details, see -[Introduction to Extensions](extension_points/introduction.md). - -For an overview of existing extension points, see [Core extension points](extension_points/core_extensions.md) and -[Base extensions](extension_points/base_extensions.md). - -## Historical context - -This is a second iteration of Dokka that was built from scratch. - -If you want to learn more about why Dokka has been designed this way, watch this great talk by Paweł Marks: -[New Dokka - Designed for Fearless Creativity](https://www.youtube.com/watch?v=OvFoTRhqaKg). The general principles -and general architecture are the same, although it may be outdated in some areas, so please double-check. diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md b/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md deleted file mode 100644 index 5264553d..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md +++ /dev/null @@ -1,245 +0,0 @@ -# Documentables Model - -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) -(for `Java`) models. Code-wise, you can have a look at following classes: - -* `DefaultDescriptorToDocumentableTranslator` - responsible for `Kotlin` -> `Documentable` mapping -* `DefaultPsiToDocumentableTranslator` - responsible for `Java` -> `Documentable` mapping - -Upon creation, it's a collection of trees, each with `DModule` as root. - -Take some arbitrary `Kotlin` source code that is located within the same module: - -```kotlin -// Package 1 -class Clazz(val property: String) { - fun function(parameter: String) {} -} - -fun topLevelFunction() {} - -// Package 2 -enum class Enum { } - -val topLevelProperty: String -``` - -This would be represented roughly as the following `Documentable` tree: - -```mermaid -flowchart TD - DModule --> firstPackage[DPackage] - firstPackage --> DClass - firstPackage --> toplevelfunction[DFunction] - DClass --> DProperty - DClass --> DFunction - DFunction --> DParameter - DModule --> secondPackage[DPackage] - secondPackage --> DEnum - secondPackage --> secondPackageProperty[DProperty] -``` - -At later stages of transformation, all trees are folded into one (by `DocumentableMerger`). - -## Documentable - -The main building block of documentables model is `Documentable` class. It's the base class for all more specific types -that represent elements of parsed sources with mostly self-explanatory names (`DFunction`, `DPackage`, `DProperty`, etc) -. -`DClasslike` is the base class for class-like documentables such as `DClass`, `DEnum`, `DAnnotation`, etc. - -The contents of each documentable normally represent what you would see in source code. For instance, if you open -`DClass`, you should find that it contains references to functions, properties, companion object, constructors and so -on. -`DEnum` should have references to enum entries, and `DPackage` can have references to both classlikes and top-level -functions and properties (`Kotlin`-specific). - -Here's an example of a documentable: - -```kotlin -data class DClass( - val dri: DRI, - val name: String, - val constructors: List<DFunction>, - val functions: List<DFunction>, - val properties: List<DProperty>, - val classlikes: List<DClasslike>, - val sources: SourceSetDependent<DocumentableSource>, - val visibility: SourceSetDependent<Visibility>, - val companion: DObject?, - val generics: List<DTypeParameter>, - val supertypes: SourceSetDependent<List<TypeConstructorWithKind>>, - val documentation: SourceSetDependent<DocumentationNode>, - val expectPresentInSet: DokkaSourceSet?, - val modifier: SourceSetDependent<Modifier>, - val sourceSets: Set<DokkaSourceSet>, - val isExpectActual: Boolean, - val extra: PropertyContainer<DClass> = PropertyContainer.empty() -) : DClasslike(), WithAbstraction, WithCompanion, WithConstructors, - WithGenerics, WithSupertypes, WithExtraProperties<DClass> -``` - -___ - -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 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 take the `limitedParallelism` function from `kotlinx.coroutines`: - -```kotlin -package kotlinx.coroutines - -import ... - -public abstract class MainCoroutineDispatcher : CoroutineDispatcher() { - - override fun limitedParallelism(parallelism: Int): CoroutineDispatcher { - ... - } -} -``` - -If we were to re-create the DRI of this function in code, it would look something like this: - -```kotlin -DRI( - packageName = "kotlinx.coroutines", - classNames = "MainCoroutineDispatcher", - callable = Callable( - name = "limitedParallelism", - receiver = null, - params = listOf( - TypeConstructor( - fullyQualifiedName = "kotlin.Int", - params = emptyList() - ) - ) - ), - target = PointingToDeclaration, - extra = null -) -``` - -If you format it as `String`, it would look like this: - -``` -kotlinx.coroutines/MainCoroutineDispatcher/limitedParallelism/#kotlin.Int/PointingToDeclaration/ -``` - -### SourceSetDependent - -`SourceSetDependent` helps handling multiplatform data by associating platform-specific data (declared with either -`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 -for `actual`. - -Under the hood, it's a `typealias` to a `Map`: - -```kotlin -typealias SourceSetDependent<T> = Map<DokkaSourceSet, T> -``` - -### ExtraProperty - -`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly -recommended to use extras to provide any additional information when creating custom Dokka plugins. - -This element is a bit more complex, so you can read more about how to use it -[in a separate section](extra.md). - -___ - -## Documentation model - -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. - -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` describes the whole comment description or a specific comment tag. -For example: `@see` / `@author` / `@return`. - |
