Extension points

Core extension points

We will discuss all base extension points along with the steps, that DokkaGenerator does to build a documentation.

Setting up Kotlin and Java analysis process and initializing plugins

The provided Maven / CLI / Gradle configuration is read.Then, all the DokkaPlugin classes are loaded and the extensions are created.

No entry points here.

Creating documentation models

The documentation models are created.

This step uses DokkaCore.sourceToDocumentableTranslator entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement SourceToDocumentableTranslator interface:

interface SourceToDocumentableTranslator {
    fun invoke(sourceSet: SourceSetData, context: DokkaContext): DModule
}
By default, two translators are created:

  • DefaultDescriptorToDocumentableTranslator that handles Kotlin files
  • DefaultPsiToDocumentableTranslator that handles Java files

After this step, all data from different source sets and languages are kept separately.

If you are using Kotlin it is recommended to make use of the asynchronous version, providing you implementation of invokeSuspending:

interface AsyncSourceToDocumentableTranslator : SourceToDocumentableTranslator {
    suspend fun invokeSuspending(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext): DModule
}

Pre-merge documentation transform

Here you can apply any transformation to model data before different source sets are merged.

This step uses DokkaCore.preMergeDocumentableTransformer entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement PreMergeDocumentableTransformer interface:

interface PreMergeDocumentableTransformer {
    operator fun invoke(modules: List<DModule>, context: DokkaContext): List<DModule>
}
By default, three transformers are created:

  • DocumentableVisibilityFilter that, depending on configuration, filters out all private members from declared packages
  • ActualTypealiasAdder that handles Kotlin typealiases
  • ModuleAndPackageDocumentationTransformer that creates documentation content for models and packages itself

Merging

All DModule instances are merged into one.

This step uses DokkaCore.documentableMerger entry point. It is required to have exactly one extension registered for this entry point. Having more will trigger an error, unless only one is not overridden.

The extension is required to implement DocumentableMerger interface:

interface DocumentableMerger {
    operator fun invoke(modules: Collection<DModule>, context: DokkaContext): DModule
}

By default, DefaultDocumentableMerger is created. This extension is treated as a fallback, so it can be overridden by a custom one.

Merged data transformation

You can apply any transformation to already merged data

This step uses DokkaCore.documentableTransformer entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement DocumentableTransformer interface:

interface DocumentableTransformer {
    operator fun invoke(original: DModule, context: DokkaContext): DModule
}

By default, InheritorsExtractorTransformer is created, that extracts inherited classes data across source sets and creates inheritance map.

Creating page models

The documentable model is translated into page format, that aggregates all tha data that will be available for different pages of documentation.

This step uses DokkaCore.documentableToPageTranslator entry point. It is required to have exactly one extension registered for this entry point. Having more will trigger an error, unless only one is not overridden.

The extension is required to implement DocumentableToPageTranslator interface:

interface DocumentableToPageTranslator {
    operator fun invoke(module: DModule): ModulePageNode
}

By default, DefaultDocumentableToPageTranslator is created. This extension is treated as a fallback, so it can be overridden by a custom one.

Transforming page models

You can apply any transformations to paged data.

This step uses DokkaCore.pageTransformer entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement PageTransformer interface:

interface PageTransformer {
    operator fun invoke(input: RootPageNode): RootPageNode
}
By default, two transformers are created:

  • PageMerger merges some pages depending on MergeStrategy
  • DeprecatedStrikethroughTransformer marks all deprecated members on every page

Rendering

All pages are rendered to desired format.

This step uses DokkaCore.renderer entry point. It is required to have exactly one extension registered for this entry point. Having more will trigger an error, unless only one is not overridden.

The extension is required to implement Renderer interface:

interface Renderer {
    fun render(root: RootPageNode)
}

By default, only HtmlRenderer, that extends basic DefaultRenderer, is created, but it will be registered only if configuration parameter format is set to html. Using any other value without providing valid renderer will cause Dokka to fail.

Multimodule page generation endpoints

Multimodule page generation is a separate process, that declares two additional entry points:

Multimodule page creation

Generation of the page that points to all module for which we generates documentation.

This step uses CoreExtensions.allModulePageCreator entry point. It is required to have exactly one extension registered for this entry point. Having more will trigger an error, unless only one is not overridden.

The extension is required to implement PageCreator interface:

interface PageCreator {
    operator fun invoke(): RootPageNode
}

By default, MultimodulePageCreator is created. This extension is treated as a fallback, so it can be replaced by a custom one.

Multimodule page transformation

Additional transformation that we might apply for multimodule page.

This step uses CoreExtensions.allModulePageTransformer entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement common PageTransformer interface.

Default extensions' extension points

Default core extension points already have an implementation for providing basic Dokka functionality. All of them are declared in DokkaBase plugin. If you don't want this default extensions to load, all you need to do is not load Dokka base and load your plugin instead.

```kotlin val customPlugin by configurations.creating

dependencies { customPlugin("[custom plugin load signature]") } tasks { val dokka by getting(DokkaTask::class) { pluginsConfig = alternativeAndIndependentPlugins outputDirectory = dokkaOutputDir outputFormat = "html" [...] } }

 You will then need to implement extensions for all core extension points. 

`DokkaBase` also register several new extension points, with which you can change default behaviour of `DokkaBase` extensions. In order to use them, you need to add `dokka-base` to you dependencies:

```kotlin
    compileOnly("org.jetbrains.dokka:dokka-base:<dokka_version>")

Then, you need to obtain DokkaBase instance using plugin function:

class SamplePlugin : DokkaPlugin() {

    val dokkaBase = plugin<DokkaBase>()

    val extension by extending {
        dokkaBase.pageMergerStrategy with SamplePageMergerStrategy order {
           before(dokkaBase.fallbackMerger)
       }
    }
}

object SamplePageMergerStrategy: PageMergerStrategy {
    override fun tryMerge(pages: List<PageNode>, path: List<String>): List<PageNode> {
        ...
    }

}

Following extension points are available with base plugin

Entry point Function Required interface Used by Singular Preregistered extensions
pageMergerStrategy determines what kind of pages should be merged PageMergerStrategy PageMerger false FallbackPageMergerStrategy SameMethodNamePageMergerStrategy
commentsToContentConverter transforms comment model into page content model CommentsToContentConverter DefaultDocumentableToPageTransformer SignatureProvider true DocTagToContentConverter
signatureProvider provides representation of methods signatures SignatureProvider DefaultDocumentableToPageTransformer true KotlinSignatureProvider
locationProviderFactory provides LocationProvider instance that returns paths for requested elements LocationProviderFactory DefaultRenderer HtmlRenderer PackageListService true DefaultLocationProviderFactory which returns DefaultLocationProvider
externalLocationProviderFactory provides ExternalLocationProvider instance that returns paths for elements that are not part of generated documentation ExternalLocationProviderFactory DefaultLocationProvider false JavadocExternalLocationProviderFactory DokkaExternalLocationProviderFactory
outputWriter writes rendered pages files OutputWriter DefaultRenderer HtmlRenderer true FileWriter
htmlPreprocessors transforms page content before HTML rendering PageTransformer DefaultRenderer HtmlRenderer false RootCreator SourceLinksTransformer NavigationPageInstaller SearchPageInstaller ResourceInstaller StyleAndScriptsAppender PackageListCreator
samplesTransformer transforms content for code samples for HTML rendering SamplesTransformer HtmlRenderer true DefaultSamplesTransformer