Параметры конфигурации Dokka Gradle

В Dokka доступно множество параметров конфигурации, позволяющих настроить работу с документацией для вас и ваших читателей.

Ниже приведены подробные описания каждого раздела конфигурации и несколько примеров. Также можно посмотреть пример, в котором применены все параметры конфигурации.

Подробнее о применении блоков конфигурации в сборках с одним и несколькими проектами см. в разделе Примеры конфигурации.

Общая конфигурация

Ниже приведён пример общей конфигурации плагина Dokka Gradle:

Используйте конфигурацию DSL верхнего уровня dokka {}.
В DGP конфигурации публикаций Dokka объявляются в блоке dokkaPublications{}.
Публикации по умолчанию: html и javadoc.
Синтаксис файлов build.gradle.kts отличается от синтаксиса обычных файлов .kt (например, файлов для пользовательских плагинов Kotlin), поскольку в Kotlin DSL Gradle используются типобезопасные аксессоры.

plugins {
    id("org.jetbrains.dokka") version "2.2.0"
}

dokka {
    dokkaPublications.html {
        moduleName.set(project.name)
        moduleVersion.set(project.version.toString())
        // Standard output directory for HTML documentation
        outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
        failOnWarning.set(false)
        suppressInheritedMembers.set(false)
        suppressObviousFunctions.set(true)
        offlineMode.set(false)
        includes.from("packages.md", "extra.md")
        
        // Output directory for additional files
        // Use this block instead of the standard when you 
        // want to change the output directory and include extra files
        outputDirectory.set(rootDir.resolve("docs/api/0.x"))
        
        // Use fileTree to add multiple files
        includes.from(
            fileTree("docs") {
                include("**/*.md")
            }
        )
    }
}

Дополнительную информацию о работе с файлами см. в документации Gradle.

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")

        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            
            dokka.moduleName.set(project.name)
            dokka.moduleVersion.set(project.version.toString())

            dokka.dokkaPublications.named("html") { publication ->
                // Standard output directory for HTML documentation
                publication.outputDirectory.set(project.layout.buildDirectory.dir("dokka/html"))
                publication.failOnWarning.set(true)
                publication.suppressInheritedMembers.set(true)
                publication.offlineMode.set(false)
                publication.suppressObviousFunctions.set(true)
                publication.includes.from("packages.md", "extra.md")

                // Output directory for additional files
                // Use this instead of the standard block when you 
                // want to change the output directory and include extra files
                html.outputDirectory.set(project.rootDir.resolve("docs/api/0.x"))
            }
        }
    }
}

plugins {
    id 'org.jetbrains.dokka' version '2.2.0'
}

dokka {
    dokkaPublications {
        html {
            // Sets general module information
            moduleName.set(project.name)
            moduleVersion.set(project.version.toString())

            // Standard output directory for HTML documentation
            outputDirectory.set(layout.buildDirectory.dir("dokka/html"))

            // Core Dokka options
            failOnWarning.set(false)
            suppressInheritedMembers.set(false)
            suppressObviousFunctions.set(true)
            offlineMode.set(false)
            includes.from(files("packages.md", "extra.md"))

            // Output directory for additional files
            // Use this block instead of the standard when you want to 
            // change the output directory and include extra files
            outputDirectory.set(file("$rootDir/docs/api/0.x"))
        }
    }
}

moduleName

Отображаемое имя документации проекта. Оно показывается в оглавлении, навигации, заголовках и сообщениях журнала. В сборках с несколькими проектами moduleName каждого подпроекта используется в качестве заголовка его раздела в агрегированной документации.

По умолчанию: имя проекта Gradle

moduleVersion

Версия подпроекта, отображаемая в сгенерированной документации. В сборках с одним проектом используется версия проекта. В сборках с несколькими проектами moduleVersion каждого подпроекта используется при агрегировании документации.

По умолчанию: версия проекта Gradle

outputDirectory

Каталог для сохранения сгенерированной документации.

Этот параметр применяется ко всем форматам документации (HTML, Javadoc и т. д.), создаваемым задачей dokkaGenerate.

По умолчанию: build/dokka/html

Каталог вывода для дополнительных файлов

Вы можете указать каталог вывода и добавить дополнительные файлы как для сборок с одним проектом, так и для сборок с несколькими проектами. Для сборок с несколькими проектами укажите каталог вывода и дополнительные файлы в конфигурации корневого проекта.

failOnWarning

Определяет, должна ли Dokka завершать сборку с ошибкой при возникновении предупреждения во время генерации документации. Процесс ожидает, пока не будут выведены все ошибки и предупреждения.

Этот параметр хорошо сочетается с reportUndocumented.

По умолчанию: false

suppressInheritedMembers

Определяет, следует ли скрывать унаследованные члены, которые явно не переопределены в данном классе.

Примечание. Этот параметр скрывает такие функции, как equals, hashCode и toString, но не скрывает синтетические функции, например dataClass.componentN и dataClass.copy. Для этого используйте suppressObviousFunctions.

По умолчанию: false

suppressObviousFunctions

Определяет, следует ли скрывать очевидные функции.

Функция считается очевидной, если она:

Унаследована от kotlin.Any, Kotlin.Enum, java.lang.Object или java.lang.Enum, например equals, hashCode, toString.
Является синтетической (созданной компилятором) и не имеет документации, например dataClass.componentN или dataClass.copy.

По умолчанию: true

offlineMode

Определяет, следует ли загружать удалённые файлы и переходить по ссылкам через сеть.

Сюда входят списки пакетов, используемые для создания ссылок на внешнюю документацию. Например, это позволяет сделать классы стандартной библиотеки кликабельными в документации.

Установка значения true может значительно ускорить сборку в некоторых случаях, но также может ухудшить удобство работы пользователей. Например, ссылки на классы и члены зависимостей, включая стандартную библиотеку, не будут разрешены.

Примечание. Вы можете кэшировать загруженные файлы локально и передавать их Dokka в виде локальных путей. См. раздел externalDocumentationLinks.

По умолчанию: false

includes

Список файлов Markdown, содержащих документацию подпроектов и пакетов. Файлы Markdown должны соответствовать требуемому формату.

Содержимое указанных файлов анализируется и встраивается в документацию в качестве описаний подпроектов и пакетов.

Пример использования и результата см. в примере Dokka Gradle.

Конфигурация набора исходного кода

Dokka позволяет задавать некоторые параметры для наборов исходного кода Kotlin:

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    // ..
    // General configuration section
    // ..

    // Source sets configuration
    dokkaSourceSets {
        // Example: Configuration exclusive to the 'linux' source set
        named("linux") {
            dependentSourceSets{named("native")}
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")
           
            sourceLink {
                // Source link section
            }
            perPackageOption {
                // Package options section
            }
            externalDocumentationLinks {
                // External documentation links section
            }
        }
    }
}

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    // ..
    // General configuration section
    // ..

    dokkaSourceSets {
        // Example: Configuration exclusive to the 'linux' source set
        named("linux") {
            dependentSourceSets { named("native") }
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([VisibilityModifier.Public] as Set) // OR documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                // Source link section
            }
            perPackageOption {
                // Package options section
            }
            externalDocumentationLinks {
                // External documentation links section
            }
        }
    }
}

suppress

Определяет, нужно ли пропустить этот набор исходного кода при генерации документации.

По умолчанию: false

displayName

Отображаемое имя, используемое для обозначения этого набора исходного кода.

Имя используется как внешними способами (например, отображается читателям документации как имя набора исходного кода), так и внутренними (например, в сообщениях журнала reportUndocumented).

По умолчанию значение определяется по информации, предоставленной плагином Kotlin Gradle.

documentedVisibilities

Определяет, какие модификаторы видимости Dokka должна включать в сгенерированную документацию.

Используйте этот параметр, если хотите документировать объявления protected, internal и private, а также если хотите исключить объявления public и документировать только внутренний API.

Кроме того, чтобы добавить документируемые уровни видимости, можно использовать функцию Dokka documentedVisibilities().

Этот параметр можно настроить отдельно для каждого пакета.

По умолчанию: VisibilityModifier.Public

reportUndocumented

Определяет, нужно ли выдавать предупреждения о видимых недокументированных объявлениях, то есть объявлениях без KDoc после фильтрации с помощью documentedVisibilities и других фильтров.

Этот параметр хорошо сочетается с failOnWarning.

Этот параметр можно настроить отдельно для каждого пакета.

По умолчанию: false

skipEmptyPackages

Определяет, нужно ли пропускать пакеты, в которых после применения различных фильтров не осталось видимых объявлений.

Например, если для skipDeprecated задано значение true и пакет содержит только устаревшие объявления, он считается пустым.

По умолчанию: true

skipDeprecated

Определяет, нужно ли документировать объявления с аннотацией @Deprecated.

Этот параметр можно настроить отдельно для каждого пакета.

По умолчанию: false

suppressGeneratedFiles

Определяет, нужно ли документировать сгенерированные файлы.

Предполагается, что сгенерированные файлы находятся в каталоге {project}/{buildDir}/generated.

Если задано значение true, все файлы из этого каталога фактически добавляются в параметр suppressedFiles, поэтому вы можете настроить его вручную.

По умолчанию: true

suppressAnnotatedWith

Набор полных квалифицированных имён (FQN) аннотаций, которыми помеченные объявления нужно скрыть.

Любое объявление с одной из этих аннотаций исключается из сгенерированной документации.

jdkVersion

Версия JDK, используемая для генерации ссылок на внешнюю документацию типов Java.

Например, если в сигнатуре некоторого общедоступного объявления используется java.util.UUID и для этого параметра задано значение 8, Dokka создаст для него ссылку на Javadocs JDK 8.

По умолчанию: `8`

languageVersion

Версия языка Kotlin, используемая для настройки анализа и среды @sample.

По умолчанию используется последняя версия языка, доступная во встроенном компиляторе Dokka.

apiVersion

Версия API Kotlin, используемая для настройки анализа и среды @sample.

По умолчанию определяется по значению languageVersion.

sourceRoots

Корневые каталоги исходного кода для анализа и документирования. Допустимые значения: каталоги и отдельные файлы .kt и .java.

По умолчанию корневые каталоги исходного кода определяются по информации, предоставленной плагином Kotlin Gradle.

classpath

Путь к классам для анализа и интерактивных примеров.

Этот параметр полезен, если некоторые типы из зависимостей не разрешаются или не обнаруживаются автоматически.

Для этого параметра можно указать файлы .jar и .klib.

По умолчанию путь к классам определяется по информации, предоставленной плагином Kotlin Gradle.

samples

Список каталогов или файлов с примерами функций, на которые ссылается тег KDoc @sample.

Конфигурация ссылок на исходный код

Настройте ссылки на исходный код, чтобы помочь читателям найти исходный код каждого объявления в удалённом репозитории. Для этой конфигурации используйте блок dokkaSourceSets.main {}.

Блок конфигурации sourceLinks {} позволяет добавить к каждой сигнатуре ссылку source, ведущую к remoteUrl с указанным номером строки. Номер строки можно настроить с помощью параметра remoteLineSuffix.

Пример см. в документации по функции count() в kotlinx.coroutines.

Синтаксис файлов build.gradle.kts отличается от синтаксиса обычных файлов .kt (например, файлов для пользовательских плагинов Gradle), поскольку в Kotlin DSL Gradle используются типобезопасные аксессоры:

// build.gradle.kts

dokka {
    dokkaSourceSets.main {
        sourceLink {
            localDirectory.set(file("src/main/kotlin"))
            remoteUrl("https://github.com/your-repo")
            remoteLineSuffix.set("#L")
        }
    }
}

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")
        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            dokka.dokkaSourceSets.named("main") { dss ->
                dss.includes.from("README.md")
                dss.sourceLink {
                    it.localDirectory.set(project.file("src/main/kotlin"))
                    it.remoteUrl("https://example.com/src")
                    it.remoteLineSuffix.set("#L")
                }
            }
        }
    }
}

dokka {
    dokkaSourceSets {
        main {
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://github.com/your-repo"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

localDirectory

Путь к локальному каталогу исходного кода. Путь должен быть относительным к корню текущего проекта.

remoteUrl

URL сервиса размещения исходного кода, доступного читателям документации, например GitHub, GitLab, Bitbucket или любого другого сервиса, предоставляющего стабильные URL файлов исходного кода. Этот URL используется для создания ссылок на исходный код объявлений.

remoteLineSuffix

Суффикс для добавления номера строки исходного кода к URL. Он помогает читателям перейти не только к файлу, но и к конкретной строке объявления.

К указанному суффиксу добавляется сам номер. Например, если для этого параметра задано значение #L, а номер строки равен 10, итоговый суффикс URL будет #L10.

Суффиксы, используемые популярными сервисами:

GitHub: #L
GitLab: #L
Bitbucket: #lines-

По умолчанию: #L

Параметры пакета

Блок конфигурации perPackageOption позволяет задавать параметры для определённых пакетов, соответствующих matchingRegex:

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    dokkaPublications.html {
        dokkaSourceSets.configureEach {
            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public)
            }
        }
    }
}

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    dokkaPublications {
        html {
            dokkaSourceSets.configureEach {
                perPackageOption {
                    matchingRegex.set(".*api.*")
                    suppress.set(false)
                    skipDeprecated.set(false)
                    reportUndocumented.set(false)
                    documentedVisibilities.set([VisibilityModifier.Public] as Set)
                }
            }
        }
    }
}

matchingRegex

Регулярное выражение для сопоставления с пакетом.

По умолчанию: .*

suppress

Определяет, нужно ли пропустить пакет при генерации документации.

По умолчанию: false

skipDeprecated

Определяет, нужно ли документировать объявления с аннотацией @Deprecated.

Этот параметр можно настроить на уровне набора исходного кода.

По умолчанию: false

reportUndocumented

Этот параметр хорошо сочетается с failOnWarning.

Этот параметр можно настроить на уровне набора исходного кода.

По умолчанию: false

documentedVisibilities

Определяет, какие модификаторы видимости Dokka должна включать в сгенерированную документацию.

Используйте этот параметр, если хотите документировать объявления protected, internal и private в этом пакете, а также если хотите исключить объявления public и документировать только внутренний API.

Кроме того, чтобы добавить документируемые уровни видимости, можно использовать функцию Dokka documentedVisibilities().

Этот параметр можно настроить на уровне набора исходного кода.

По умолчанию: VisibilityModifier.Public

Конфигурация ссылок на внешнюю документацию

Блок externalDocumentationLinks {} позволяет создавать ссылки на документацию зависимостей, размещённую на внешних ресурсах.

Например, если вы используете типы из kotlinx.serialization, по умолчанию на них нельзя перейти из документации, как будто они не разрешены. Однако, поскольку справочная документация API для kotlinx.serialization создаётся с помощью Dokka и опубликована на kotlinlang.org, для неё можно настроить ссылки на внешнюю документацию. Это позволяет Dokka создавать ссылки на типы библиотеки, чтобы они разрешались и становились кликабельными.

По умолчанию ссылки на внешнюю документацию настроены для стандартной библиотеки Kotlin, JDK, Android SDK и AndroidX.

Зарегистрируйте ссылки на внешнюю документацию с помощью метода register(), указав каждую ссылку отдельно. В API externalDocumentationLinks этот метод используется в соответствии с соглашениями Gradle DSL:

dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url("https://example.com/docs/")
            packageListUrl("https://example.com/docs/package-list")
        }
    }
}

dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url.set(new URI("https://example.com/docs/"))
            packageListUrl.set(new URI("https://example.com/docs/package-list"))
        }
    }
}

url

Корневой URL документации, на которую нужно ссылаться. Он должен заканчиваться косой чертой.

Dokka старается автоматически найти package-list для указанного URL и связать объявления с документацией.

Если автоматическое разрешение не удаётся или вы хотите использовать локально кэшированные файлы, рассмотрите возможность настройки параметра packageListUrl.

packageListUrl

Точное расположение package-list. Это альтернатива автоматическому поиску этого файла средствами Dokka.

Списки пакетов содержат информацию о документации и самом проекте, например имена подпроектов и пакетов.

Чтобы избежать сетевых запросов, здесь также можно указать локально кэшированный файл.

Полная конфигурация

Ниже показаны все возможные параметры конфигурации, применённые одновременно:

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

plugins {
    id("org.jetbrains.dokka") version "2.2.0"
}

dokka {
    dokkaPublications.html {
        moduleName.set(project.name)
        moduleVersion.set(project.version.toString())
        outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
        failOnWarning.set(false)
        suppressInheritedMembers.set(false)
        suppressObviousFunctions.set(true)
        offlineMode.set(false)
        includes.from("packages.md", "extra.md")
   }

    dokkaSourceSets {
        // Example: Configuration exclusive to the 'linux' source set
        named("linux") {
            dependentSourceSets{named("native")}
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl("https://example.com/src")
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLinks {
                url = URL("https://example.com/docs/")
                packageListUrl = File("/path/to/package-list").toURI().toURL()
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(
                    setOf(
                        VisibilityModifier.Public,
                        VisibilityModifier.Private,
                        VisibilityModifier.Protected,
                        VisibilityModifier.Internal,
                        VisibilityModifier.Package
                    )
                )
            }
        }
    }
}

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

plugins {
    id 'org.jetbrains.dokka' version '2.2.0'
}

dokka {
    dokkaPublications {
        html {
            moduleName.set(project.name)
            moduleVersion.set(project.version.toString())
            outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
            failOnWarning.set(false)
            suppressInheritedMembers.set(false)
            suppressObviousFunctions.set(true)
            offlineMode.set(false)
            includes.from("packages.md", "extra.md")
        }
    }

    dokkaSourceSets {
        // Example: Configuration exclusive to the 'linux' source set
        named("linux") {
            dependentSourceSets { named("native") }
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([VisibilityModifier.Public] as Set)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://example.com/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLinks {
                url.set(new URI("https://example.com/docs/"))
                packageListUrl.set(new File("/path/to/package-list").toURI().toURL())
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set([
                        VisibilityModifier.Public,
                        VisibilityModifier.Private,
                        VisibilityModifier.Protected,
                        VisibilityModifier.Internal,
                        VisibilityModifier.Package
                ] as Set)
            }
        }
    }
}

16 апреля 2026 г.

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/dokka-gradle-configuration-options.html