Maven

Для создания документации проекта на Maven можно использовать плагин Maven для Dokka.

Вы можете поэкспериментировать с Dokka и узнать, как настроить его для проекта Maven, ознакомившись с проектом примера Maven.

Подключение Dokka

Чтобы подключить Dokka, добавьте dokka-maven-plugin в раздел plugins файла POM:

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.dokka</groupId>
            <artifactId>dokka-maven-plugin</artifactId>
            <version>2.2.0</version>
            <executions>
                <execution>
                    <phase>pre-site</phase>
                    <goals>
                        <goal>dokka</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Создание документации

Плагин Maven предоставляет следующие цели:

Цель	Описание
`dokka:dokka`	Создает документацию с подключенными плагинами Dokka. По умолчанию используется формат HTML.

Экспериментальные

Цель	Описание
`dokka:javadoc`	Создает документацию в формате Javadoc.
`dokka:javadocJar`	Создает файл `javadoc.jar`, содержащий документацию в формате Javadoc.

Другие форматы вывода

По умолчанию плагин Maven для Dokka создает документацию в формате вывода HTML.

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

Например, чтобы использовать экспериментальный формат GFM, необходимо добавить артефакт gfm-plugin:

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <dokkaPlugins>
            <plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>gfm-plugin</artifactId>
                <version>2.2.0</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

При такой конфигурации запуск цели dokka:dokka создает документацию в формате GFM.

Подробнее о плагинах Dokka см. в разделе Плагины Dokka.

Сборка javadoc.jar

Если вы хотите опубликовать библиотеку в репозитории, может потребоваться предоставить файл javadoc.jar с документацией API вашей библиотеки.

Например, для публикации в Maven Central вы обязаны предоставить файл javadoc.jar вместе с проектом. Однако это требование есть не во всех репозиториях.

В отличие от плагина Dokka для Gradle, плагин Maven уже содержит готовую цель dokka:javadocJar. По умолчанию она создает документацию в формате вывода Javadoc в папке target.

Если встроенная цель вас не устраивает или вы хотите настроить вывод (например, создать документацию в формате HTML вместо Javadoc), аналогичного результата можно добиться, добавив плагин Maven JAR со следующей конфигурацией:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.3.0</version>
    <executions>
        <execution>
            <goals>
                <goal>test-jar</goal>
            </goals>
        </execution>
        <execution>
            <id>dokka-jar</id>
            <phase>package</phase>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <classifier>dokka</classifier>
                <classesDirectory>${project.build.directory}/dokka</classesDirectory>
                <skipIfEmpty>true</skipIfEmpty>
            </configuration>
        </execution>
    </executions>
</plugin>

Документация и архив .jar для нее создаются при запуске целей dokka:dokka и jar:jar@dokka-jar:

mvn dokka:dokka jar:jar@dokka-jar

Пример конфигурации

Для настройки Dokka можно использовать блок конфигурации плагина Maven.

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

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <outputDir>${project.basedir}/target/documentation/dokka</outputDir>
    </configuration>
</plugin>

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

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

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

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

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <skip>false</skip>
        <moduleName>${project.artifactId}</moduleName>
        <outputDir>${project.basedir}/target/documentation</outputDir>
        <failOnWarning>false</failOnWarning>
        <suppressObviousFunctions>true</suppressObviousFunctions>
        <suppressInheritedMembers>false</suppressInheritedMembers>
        <offlineMode>false</offlineMode>
        <sourceDirectories>
            <dir>${project.basedir}/src</dir>
        </sourceDirectories>
        <documentedVisibilities>
            <visibility>PUBLIC</visibility>
            <visibility>PROTECTED</visibility>
        </documentedVisibilities>
        <reportUndocumented>false</reportUndocumented>
        <skipDeprecated>false</skipDeprecated>
        <skipEmptyPackages>true</skipEmptyPackages>
        <suppressedFiles>
            <file>/path/to/dir</file>
            <file>/path/to/file</file>
        </suppressedFiles>
        <suppressAnnotatedWith>
            <annotation>com.example.SuppressMe</annotation>
        </suppressAnnotatedWith>
        <jdkVersion>8</jdkVersion>
        <languageVersion>1.7</languageVersion>
        <apiVersion>1.7</apiVersion>
        <noStdlibLink>false</noStdlibLink>
        <noJdkLink>false</noJdkLink>
        <includes>
            <include>packages.md</include>
            <include>extra.md</include>
        </includes>
        <classpath>${project.compileClasspathElements}</classpath>
        <samples>
            <dir>${project.basedir}/samples</dir>
        </samples>
        <sourceLinks>
            <!-- Separate section -->
        </sourceLinks>
        <externalDocumentationLinks>
            <!-- Separate section -->
        </externalDocumentationLinks>
        <perPackageOptions>
            <!-- Separate section -->
        </perPackageOptions>
    </configuration>
</plugin>

skip

Пропускать ли создание документации.

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

moduleName

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

По умолчанию: {project.artifactId}

outputDir

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

По умолчанию: {project.basedir}/target/dokka

failOnWarning

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

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

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

suppressObviousFunctions

Скрывать ли очевидные функции.

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

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

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

suppressInheritedMembers

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

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

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

offlineMode

Разрешать ли получение удаленных файлов и ссылок через сеть.

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

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

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

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

sourceDirectories

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

По умолчанию: {project.compileSourceRoots}

documentedVisibilities

Набор модификаторов видимости, которые следует документировать.

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

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

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

reportUndocumented

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

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

Его можно переопределить на уровне пакета.

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

skipDeprecated

Документировать ли объявления с аннотацией @Deprecated.

Этот параметр можно переопределить на уровне пакета.

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

skipEmptyPackages

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

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

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

suppressedFiles

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

suppressAnnotatedWith

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

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

jdkVersion

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

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

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

languageVersion

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

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

apiVersion

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

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

noStdlibLink

Создавать ли ссылки на внешнюю документацию со справочником API стандартной библиотеки Kotlin.

Примечание: ссылки создаются, если для noStdLibLink задано значение false.

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

noJdkLink

Создавать ли ссылки на внешнюю документацию Javadocs для JDK.

Версия Javadocs для JDK определяется параметром jdkVersion.

Примечание: ссылки создаются, если для noJdkLink задано значение false.

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

includes

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

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

classpath

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

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

По умолчанию: {project.compileClasspathElements}

samples

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

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

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

Это помогает читателям находить исходный код каждого объявления.

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

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <sourceLinks>
            <link>
                <path>src</path>
                <url>https://github.com/kotlin/dokka/tree/master/src</url>
                <lineSuffix>#L</lineSuffix>
            </link>
        </sourceLinks>
    </configuration>
</plugin>

path

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

Примечание: допускаются только пути в формате Unix; пути в формате Windows приведут к ошибке.

url

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

lineSuffix

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

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

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

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

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

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

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

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

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <externalDocumentationLinks>
            <link>
                <url>https://kotlinlang.org/api/kotlinx.serialization/</url>
                <packageListUrl>file:/${project.basedir}/serialization.package.list</packageListUrl>
            </link>
        </externalDocumentationLinks>
    </configuration>
</plugin>

url

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

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

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

packageListUrl

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

Списки пакетов содержат сведения о документации и самом проекте, например имена модулей и пакетов.

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

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

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

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <perPackageOptions>
            <packageOptions>
                <matchingRegex>.*api.*</matchingRegex>
                <suppress>false</suppress>
                <reportUndocumented>false</reportUndocumented>
                <skipDeprecated>false</skipDeprecated>
                <documentedVisibilities>
                    <visibility>PUBLIC</visibility>
                    <visibility>PRIVATE</visibility>
                    <visibility>PROTECTED</visibility>
                    <visibility>INTERNAL</visibility>
                    <visibility>PACKAGE</visibility>
                </documentedVisibilities>
            </packageOptions>
        </perPackageOptions>
    </configuration>
</plugin>

matchingRegex

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

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

suppress

Пропускать ли этот пакет при создании документации.

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

documentedVisibilities

Набор модификаторов видимости, которые следует документировать.

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

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

skipDeprecated

Документировать ли объявления с аннотацией @Deprecated.

Этот параметр можно задать на уровне проекта/модуля.

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

reportUndocumented

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

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

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

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

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <skip>false</skip>
        <moduleName>${project.artifactId}</moduleName>
        <outputDir>${project.basedir}/target/documentation</outputDir>
        <failOnWarning>false</failOnWarning>
        <suppressObviousFunctions>true</suppressObviousFunctions>
        <suppressInheritedMembers>false</suppressInheritedMembers>
        <offlineMode>false</offlineMode>
        <sourceDirectories>
            <dir>${project.basedir}/src</dir>
        </sourceDirectories>
        <documentedVisibilities>
            <visibility>PUBLIC</visibility>
            <visibility>PRIVATE</visibility>
            <visibility>PROTECTED</visibility>
            <visibility>INTERNAL</visibility>
            <visibility>PACKAGE</visibility>
        </documentedVisibilities>
        <reportUndocumented>false</reportUndocumented>
        <skipDeprecated>false</skipDeprecated>
        <skipEmptyPackages>true</skipEmptyPackages>
        <suppressedFiles>
            <file>/path/to/dir</file>
            <file>/path/to/file</file>
        </suppressedFiles>
        <jdkVersion>8</jdkVersion>
        <languageVersion>1.7</languageVersion>
        <apiVersion>1.7</apiVersion>
        <noStdlibLink>false</noStdlibLink>
        <noJdkLink>false</noJdkLink>
        <includes>
            <include>packages.md</include>
            <include>extra.md</include>
        </includes>
        <classpath>${project.compileClasspathElements}</classpath>
        <samples>
            <dir>${project.basedir}/samples</dir>
        </samples>
        <sourceLinks>
            <link>
                <path>src</path>
                <url>https://github.com/kotlin/dokka/tree/master/src</url>
                <lineSuffix>#L</lineSuffix>
            </link>
        </sourceLinks>
        <externalDocumentationLinks>
            <link>
                <url>https://kotlinlang.org/api/core/kotlin-stdlib/</url>
                <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl>
            </link>
        </externalDocumentationLinks>
        <perPackageOptions>
            <packageOptions>
                <matchingRegex>.*api.*</matchingRegex>
                <suppress>false</suppress>
                <reportUndocumented>false</reportUndocumented>
                <skipDeprecated>false</skipDeprecated>
                <documentedVisibilities>
                    <visibility>PUBLIC</visibility>
                    <visibility>PRIVATE</visibility>
                    <visibility>PROTECTED</visibility>
                    <visibility>INTERNAL</visibility>
                    <visibility>PACKAGE</visibility>
                </documentedVisibilities>
            </packageOptions>
        </perPackageOptions>
    </configuration>
</plugin>

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-maven.html