repository·master·Indexed 25 days ago
https://github.com/kotlin/dokkaDokka is an API documentation engine for Kotlin that supports mixed-language projects (Kotlin and Java) and generates documentation in HTML, Markdown, and Javadoc formats. It includes specialized plugins such as the All Modules plugin for multi-module projects and an Android documentation plugin for @hide KDoc tag support. The engine utilizes the analysis-kotlin-api for implementation-agnostic interaction with Kotlin declarations.
The Templating plugin is an internal component used by Dokka, specifically by the HTML format, to manage template processing. Its primary responsibilities include:
Dokka is an API documentation engine for Kotlin that supports mixed-language projects. It processes both Kotlin's KDoc comments and Java's Javadoc comments to generate documentation.
Supported output formats include:
You can integrate Dokka into your workflow using Gradle, Maven, or the Command Line Interface (CLI).
This example project demonstrates how to create and configure a custom Dokka plugin using the Dokka Gradle Plugin (DGPv2) architecture. It is composed of two main parts:
dokka-plugin-hide-internal-api: A subproject containing a custom implementation of the HideInternalApiPlugin.demo-library: A subproject that demonstrates how to apply and configure the HideInternalApiPlugin to a library.For comprehensive instructions on developing plugins, refer to the official Dokka developer documentation.
Dokka uses a multi-layered abstraction model to transform source code into documentation. This allows developers to extend specific parts of the process (like filtering declarations or changing output formats) without modifying the entire engine.
The pipeline follows this flow:
By targeting specific layers, you can perform tasks like:
Documentables level to make certain annotations or classes invisible.Pages layer to merge multiple pages (e.g., grouping overloaded methods).The Documentable model is the core data representation of parsed programming language sources in Dokka. It represents code elements as a collection of trees, where each tree is rooted with a DModule.
Key characteristics:
DefaultDescriptorToDocumentableTranslator (Kotlin K1), DefaultSymbolToDocumentableTranslator (Kotlin K2), and DefaultPsiToDocumentableTranslator (Java).DPackage contains DClass, which contains DFunction).DocumentableMerger.Dokka is extensible through various plugins that add specific documentation capabilities, such as multi-module support, platform-specific improvements, or additional output formats. Use these plugins to customize your documentation generation process.
| Plugin project | Description |
|----------------|-----------------------------------------------------------------------------------------------|
| [plugin-all-modules-page](plugin-all-modules-page) | Provides the ability to generate multi-module documentation. |
| [plugin-android-documentation](plugin-android-documentation) | Improves documentation experience on the Android platform. |
| [plugin-base](plugin-base) | Includes base Dokka features and extensions, along with the built-in HTML format |
| [plugin-gfm](plugin-gfm) | Provides the ability to generate documentation in `GitHub Flavoured Markdown` format. |
| [plugin-javadoc](plugin-javadoc) | Provides the ability to generate documentation in Javadoc format. |
| [plugin-jekyll](plugin-jekyll) | Provides the ability to generate documentation in `Jekyll Flavoured Markdown` format. |
| [plugin-kotlin-as-java](plugin-kotlin-as-java) | Renders all Kotlin signatures as Java signatures. |
| [plugin-kotlin-playground-samples](plugin-kotlin-playground-samples) | Makes @sample code blocks interactive and runnable using Kotlin Playground. |
| [plugin-mathjax](plugin-mathjax) | Allows rendering mathematics in the web pages. |
| [plugin-templating](plugin-templating) | An internal Dokka plugin that handles HTML template processing. |
| [plugin-versioning](plugin-versioning) | Provides the ability to host documentation for multiple versions of your library/application. |The Page model defines the structure of documentation pages. Each Page corresponds to exactly one output file and is independent of the final output format (e.g., HTML, Markdown). The model is represented as a tree starting from a RootPageNode.
Key concepts:
PageNode: Represent different page types like ModulePage, PackagePage, ClasslikePage, and MemberPage.ContentPage: A specific type of page that contains user-visible content.Renderer extension determines the file extension and how the page is physically created.The analysis-kotlin-symbols project provides a symbols-based implementation for the analysis-kotlin-api (also known as K2 or "the new compiler").
Warning: This project contains no stable public API and must not be used directly. It should only be accessed via the analysis-kotlin-api package. It is intended to be added as a runtime dependency by the runner.
The Documentation model stores data parsed from code comments (KDocs/Javadocs) and works alongside the Documentable model.
DocumentationNode: A container for multiple TagWrapper elements for a specific Documentable.TagWrapper: Describes a specific comment tag or the entire comment description (e.g., @see, @author, @return). Each wrapper can contain DocTag children.DocTag: Describes specific syntax elements (e.g., H1, Strong, CodeBlock). Tags can be deeply nested.// Example of DocTag implementations
data class H1(
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()