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>1.8.20</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>1.8.20</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

С этой конфигурацией, выполнение цели dokka:dokka генерирует документацию в формате GFM.

Дополнительную информацию о плагинах Dokka можно найти в разделе Плагины Dokka.

Сборка javadoc.jar

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

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

В отличие от плагина Gradle для Dokka, плагин 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

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

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

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

<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>
        <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

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

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

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

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

skipDeprecated

Документировать ли объявления, аннотированные с помощью @Deprecated.

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

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

skipEmptyPackages

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

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

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

suppressedFiles

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

jdkVersion

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

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

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

languageVersion

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

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

apiVersion

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

По умолчанию она выводится из languageVersion.

noStdlibLink

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

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

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

noJdkLink

Генерировать ли внешние ссылки на Javadocs JDK.

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

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

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

includes

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

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

classpath

Classpath для анализа и интерактивных примеров.

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

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

samples

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

Настройка ссылок на исходный код

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

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

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

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

path

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

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

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

Эта настройка хорошо сочетается с 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>${project.basedir}/src</path>
                <url>https://github.com/kotlin/dokka/tree/master/src</url>
                <lineSuffix>#L</lineSuffix>
            </link>
        </sourceLinks>
        <externalDocumentationLinks>
            <link>
                <url>https://kotlinlang.org/api/latest/jvm/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>

Последнее изменение: 25 июля 2023 г.

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