Gradle

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

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

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

Применение Dokka

Рекомендуемый способ применения плагина Gradle для Dokka — использование DSL для плагинов:

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

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

При документировании многопроектных сборок необходимо также применять плагин Gradle для Dokka внутри подпроектов. Для этого можно использовать allprojects {} или subprojects {} конфигурации Gradle:

subprojects {
    apply(plugin = "org.jetbrains.dokka")
}

subprojects {
    apply plugin: 'org.jetbrains.dokka'
}

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

Если по какой-то причине вы не можете использовать DSL для плагинов, вы можете использовать старый метод применения плагинов.

END_OF_DOCUMENT_MARKER

Генерация документации

Плагин Gradle для Dokka поставляется с встроенными форматами вывода документации: HTML, Markdown и Javadoc. Он добавляет ряд задач для генерации документации, как для одномодульных, так и для многомодульных проектов.

Одномодульные проекты

Используйте следующие задачи для построения документации для простых одномодульных приложений и библиотек:

Задача	Описание
`dokkaHtml`	Генерирует документацию в формате HTML.

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

Задача	Описание
`dokkaGfm`	Генерирует документацию в формате GitHub Flavored Markdown.
`dokkaJavadoc`	Генерирует документацию в формате Javadoc.
`dokkaJekyll`	Генерирует документацию в формате Jekyll совместимого Markdown.

По умолчанию сгенерированная документация находится в каталоге build/dokka/{format} вашего проекта. Путь к выводу, среди прочего, можно настроить.

Многомодульные проекты

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

Задачи для многомодульных проектов

Задачи MultiModule генерируют документацию для каждого подпроекта индивидуально через задачи Partial, собирают и обрабатывают все результаты и создают полную документацию с общим оглавлением и разрешенными межпроектными ссылками.

Dokka автоматически создаёт следующие задачи для родительских проектов:

Задача	Описание
`dokkaHtmlMultiModule`	Генерирует документацию для многомодульных проектов в формате HTML.

Экспериментальные форматы (многомодульные)

Задача	Описание
`dokkaGfmMultiModule`	Генерирует многомодульную документацию в формате GitHub Flavored Markdown.
`dokkaJekyllMultiModule`	Генерирует многомодульную документацию в формате Jekyll совместимого Markdown.

По умолчанию готовую документацию можно найти в каталоге {parentProject}/build/dokka/{format}MultiModule.

Результаты многомодульных задач

Предположим проект со следующей структурой:

parentProject
    └── childProjectA
        ├── demo
            ├── ChildProjectAClass
    └── childProjectB
        ├── demo
            ├── ChildProjectBClass

Эти страницы генерируются после выполнения dokkaHtmlMultiModule:

Screenshot for output of dokkaHtmlMultiModule task

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

Задачи-коллекторы

Аналогично задачам MultiModule для каждого родительского проекта создаются задачи Collector, dokkaHtmlCollector, dokkaGfmCollector, dokkaJavadocCollector и dokkaJekyllCollector.

Задача Collector выполняет соответствующую задачу одномодульного проекта для каждого подпроекта (например, dokkaHtml) и объединяет все результаты в один виртуальный проект.

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

Результаты задач-коллекторов

Предположим проект со следующей структурой:

parentProject
    └── childProjectA
        ├── demo
            ├── ChildProjectAClass
    └── childProjectB
        ├── demo
            ├── ChildProjectBClass

Эти страницы генерируются после выполнения dokkaHtmlCollector:

Screenshot for output of dokkaHtmlCollector task

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

Частичные задачи

Каждый подпроект имеет задачи Partial: dokkaHtmlPartial, dokkaGfmPartial и dokkaJekyllPartial.

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

Однако, вы можете настроить задачи Partial для настройки Dokka для ваших подпроектов.

Создание javadoc.jar

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

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

Плагин Gradle для Dokka не предоставляет прямой способ сделать это, но это можно реализовать с помощью пользовательских задач Gradle. Одна для генерации документации в формате HTML, а другая для Javadoc:

tasks.register<Jar>("dokkaHtmlJar") {
    dependsOn(tasks.dokkaHtml)
    from(tasks.dokkaHtml.flatMap { it.outputDirectory })
    archiveClassifier.set("html-docs")
}

tasks.register<Jar>("dokkaJavadocJar") {
    dependsOn(tasks.dokkaJavadoc)
    from(tasks.dokkaJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

tasks.register('dokkaHtmlJar', Jar.class) {
    dependsOn(dokkaHtml)
    from(dokkaHtml)
    archiveClassifier.set("html-docs")
}

tasks.register('dokkaJavadocJar', Jar.class) {
    dependsOn(dokkaJavadoc)
    from(dokkaJavadoc)
    archiveClassifier.set("javadoc")
}

END_OF_DOCUMENT_MARKER

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

В зависимости от типа проекта, способ применения и конфигурации Dokka немного отличается. Однако, опции конфигурации сами по себе одинаковы, независимо от типа вашего проекта.

Для простых и плоских проектов с одним файлом build.gradle.kts или build.gradle в корне вашего проекта, см. Конфигурацию для одного проекта.

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

Конфигурация для одного проекта

Сборки одного проекта обычно содержат только один файл build.gradle.kts или build.gradle в корне проекта и, как правило, имеют следующую структуру:

Одна платформа:

.
├── build.gradle.kts
└── src
    └── main
        └── kotlin
            └── HelloWorld.kt

Мультиплатформа:

.
├── build.gradle.kts
└── src
    └── commonMain
        └── kotlin
            └── Common.kt
    └── jvmMain
        └── kotlin
            └── JvmUtils.kt
    └── nativeMain
        └── kotlin
            └── NativeUtils.kt

Одна платформа:

.
├── build.gradle
└── src
    └── main
        └── kotlin
            └── HelloWorld.kt

Мультиплатформа:

.
├── build.gradle
└── src
    └── commonMain
        └── kotlin
            └── Common.kt
    └── jvmMain
        └── kotlin
            └── JvmUtils.kt
    └── nativeMain
        └── kotlin
            └── NativeUtils.kt

В таких проектах вам нужно применить Dokka и его конфигурацию в корневом файле build.gradle.kts или build.gradle.

Вы можете настроить задачи и форматы вывода индивидуально:

Внутри ./build.gradle.kts:

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

tasks.dokkaHtml {
    outputDirectory.set(buildDir.resolve("documentation/html"))
}

tasks.dokkaGfm {
    outputDirectory.set(buildDir.resolve("documentation/markdown"))
}

Внутри ./build.gradle:

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

dokkaHtml {
    outputDirectory.set(file("build/documentation/html"))
}

dokkaGfm {
    outputDirectory.set(file("build/documentation/markdown"))
}

Или вы можете настроить все задачи и форматы вывода одновременно:

Внутри ./build.gradle.kts:

import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import org.jetbrains.dokka.DokkaConfiguration.Visibility

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

// Configure all single-project Dokka tasks at the same time, 
// such as dokkaHtml, dokkaJavadoc and dokkaGfm.
tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set(
            setOf(
                Visibility.PUBLIC,
                Visibility.PROTECTED,
            )
        )

        perPackageOption {
            matchingRegex.set(".*internal.*")
            suppress.set(true)
        }
    }
}

Внутри ./build.gradle:

import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import org.jetbrains.dokka.DokkaConfiguration.Visibility

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

// Configure all single-project Dokka tasks at the same time, 
// such as dokkaHtml, dokkaJavadoc and dokkaGfm.
tasks.withType(DokkaTask.class) {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set([
                Visibility.PUBLIC,
                Visibility.PROTECTED
        ])

        perPackageOption {
            matchingRegex.set(".*internal.*")
            suppress.set(true)
        }
    }
}

Конфигурация для нескольких проектов

Сборки нескольких проектов Gradle имеют более сложную структуру и конфигурацию. Обычно они содержат несколько вложенных файлов build.gradle.kts или build.gradle, и, как правило, имеют следующую структуру:

.
├── build.gradle.kts
├── settings.gradle.kts
├── subproject-A
    └── build.gradle.kts
    └── src
        └── main
            └── kotlin
                └── HelloFromA.kt
├── subproject-B
    └── build.gradle.kts
    └── src
        └── main
            └── kotlin
                └── HelloFromB.kt

.
├── build.gradle
├── settings.gradle
├── subproject-A
    └── build.gradle
    └── src
        └── main
            └── kotlin
                └── HelloFromA.kt
├── subproject-B
    └── build.gradle
    └── src
        └── main
            └── kotlin
                └── HelloFromB.kt

В этом случае существует несколько способов применения и конфигурации Dokka.

Конфигурация подпроектов

Чтобы настроить подпроекты в многопроектной сборке, вам необходимо настроить задачи Partial.

Вы можете настроить все подпроекты одновременно в корневом файле build.gradle.kts или build.gradle, используя блоки конфигурации Gradle allprojects {} или subprojects {}:

В корневом файле ./build.gradle.kts:

import org.jetbrains.dokka.gradle.DokkaTaskPartial

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

subprojects {
    apply(plugin = "org.jetbrains.dokka")

    // configure only the HTML task
    tasks.dokkaHtmlPartial {
        outputDirectory.set(buildDir.resolve("docs/partial"))
    }

    // configure all format tasks at once
    tasks.withType<DokkaTaskPartial>().configureEach {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}

В корневом файле ./build.gradle:

import org.jetbrains.dokka.gradle.DokkaTaskPartial

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

subprojects {
    apply plugin: 'org.jetbrains.dokka'

    // configure only the HTML task
    dokkaHtmlPartial {
        outputDirectory.set(file("build/docs/partial"))
    }

    // configure all format tasks at once
    tasks.withType(DokkaTaskPartial.class) {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}

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

Например, чтобы иметь специфические настройки только для подпроекта subproject-A, вам необходимо добавить следующий код в ./subproject-A/build.gradle.kts:

Внутри ./subproject-A/build.gradle.kts:

apply(plugin = "org.jetbrains.dokka")

// configuration for subproject-A only.
tasks.dokkaHtmlPartial {
    outputDirectory.set(buildDir.resolve("docs/partial"))
}

Внутри ./subproject-A/build.gradle:

apply plugin: 'org.jetbrains.dokka'

// configuration for subproject-A only.
dokkaHtmlPartial {
    outputDirectory.set(file("build/docs/partial"))
}

Конфигурация родительского проекта

Если вы хотите настроить что-то универсальное для всей документации, что не принадлежит подпроектам — другими словами, это свойство родительского проекта — вам необходимо настроить задачи MultiModule.

Например, если вы хотите изменить имя своего проекта, используемое в заголовке HTML-документации, вам нужно добавить следующее в корневой файл build.gradle.kts или build.gradle:

В корневом файле ./build.gradle.kts:

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

tasks.dokkaHtmlMultiModule {
    moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER")
}

В корневом файле ./build.gradle:

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

dokkaHtmlMultiModule {
    moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER")
}

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

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

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

См. Примеры конфигурации для получения более подробной информации о том, где применять блоки конфигурации и как.

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

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

import org.jetbrains.dokka.gradle.DokkaTask

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType<DokkaTask>().configureEach {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(buildDir.resolve("dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)
    
    // ..
    // source set configuration section
    // ..
}

import org.jetbrains.dokka.gradle.DokkaTask

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType(DokkaTask.class) {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(file("build/dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    // ..
    // source set configuration section
    // ..
}

moduleName

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

Если установлено для сборки одного проекта или для задачи MultiModule, оно используется как имя проекта.

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

moduleVersion

Версия модуля. Если установлено для сборки одного проекта или для задачи MultiModule, оно используется как версия проекта.

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

outputDirectory

Директория, в которую генерируется документация, независимо от формата. Ее можно установить для каждой задачи.

По умолчанию {project}/{buildDir}/{format}, где {format} — это имя задачи без префикса "dokka". Для задачи dokkaHtmlMultiModule это project/buildDir/htmlMultiModule.

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

END_OF_DOCUMENT_MARKER

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

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

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // ..

    dokkaSourceSets {
        // configuration exclusive to the 'linux' source set
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

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

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // ..
    
    dokkaSourceSets {
        // configuration exclusive to the 'linux' source set 
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([Visibility.PUBLIC])
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

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

suppress

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

Значение по умолчанию: false

displayName

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

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

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

documentedVisibilities

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

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

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

Значение по умолчанию: DokkaConfiguration.Visibility.PUBLIC

reportUndocumented

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

Эта настройка хорошо работает с failOnWarning.

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

Значение по умолчанию: false

skipEmptyPackages

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

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

Значение по умолчанию: true

skipDeprecated

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

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

Значение по умолчанию: false

suppressGeneratedFiles

Документировать/анализировать ли сгенерированные файлы.

Ожидается, что сгенерированные файлы будут находиться в каталоге {project}/{buildDir}/generated.

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

Значение по умолчанию: true

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

noAndroidSdkLink

Генерировать ли внешние ссылки на справочную документацию API Android SDK.

Это актуально только в проектах Android, в противном случае игнорируется.

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

Значение по умолчанию: false

includes

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

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

См. пример Dokka gradle для примера того, как это выглядит и как его использовать.

platform

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

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

sourceRoots

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

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

classpath

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

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

Этот параметр принимает как файлы .jar, так и файлы .klib.

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

samples

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

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

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

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

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

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ..
        
        sourceLink {
            localDirectory.set(projectDir.resolve("src"))
            remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
            remoteLineSuffix.set("#L")
        }
    }
}

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ..
        
        sourceLink {
            localDirectory.set(file("src"))
            remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src"))
            remoteLineSuffix.set("#L")
        }
    }
}

localDirectory

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

remoteUrl

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

remoteLineSuffix

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

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

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

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

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

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

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

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ..
        
        perPackageOption {
            matchingRegex.set(".*api.*")
            suppress.set(false)
            skipDeprecated.set(false)
            reportUndocumented.set(false)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
        }
    }
}

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation.
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // Source set configuration section
        // ..
        
        perPackageOption {
            matchingRegex.set(".*api.*")
            suppress.set(false)
            skipDeprecated.set(false)
            reportUndocumented.set(false)
            documentedVisibilities.set([Visibility.PUBLIC])
        }
    }
}

matchingRegex

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

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

suppress

Нужно ли пропускать этот пакет при генерации документации.

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

skipDeprecated

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

Это можно настроить на уровне набора исходных файлов.

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

reportUndocumented

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

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

Это можно настроить на уровне набора исходных файлов.

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

documentedVisibilities

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

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

Это можно настроить на уровне набора исходных файлов.

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

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

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

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

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

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ..
        
        externalDocumentationLink {
            url.set(URL("https://kotlinlang.org/api/kotlinx.serialization/"))
            packageListUrl.set(
                rootProject.projectDir.resolve("serialization.package.list").toURL()
            )
        }
    }
}

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ..
        
        externalDocumentationLink {
            url.set(new URL("https://kotlinlang.org/api/kotlinx.serialization/"))
            packageListUrl.set(
                file("serialization.package.list").toURL()
            )
        }
    }
}

url

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

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

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

packageListUrl

Точное расположение package-list. Это альтернатива автоматическому разрешению Dokka.

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

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

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

Ниже показан весь набор возможных опций конфигурации, применённых одновременно.

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType<DokkaTask>().configureEach {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(buildDir.resolve("dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    dokkaSourceSets {
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")
            
            sourceLink {
                localDirectory.set(projectDir.resolve("src"))
                remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLink {
                url.set(URL("https://kotlinlang.org/api/latest/jvm/stdlib/"))
                packageListUrl.set(
                    rootProject.projectDir.resolve("stdlib.package.list").toURL()
                )
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(
                    setOf(
                        Visibility.PUBLIC,
                        Visibility.PRIVATE,
                        Visibility.PROTECTED,
                        Visibility.INTERNAL,
                        Visibility.PACKAGE
                    )
                )
            }
        }
    }
}

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// Note: To configure multi-project builds, you need 
//       to configure Partial tasks of the subprojects. 
//       See "Configuration example" section of documentation. 
tasks.withType(DokkaTask.class) {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(file("build/dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    dokkaSourceSets {
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([Visibility.PUBLIC])
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src"))
                remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLink {
                url.set(new URL("https://kotlinlang.org/api/latest/jvm/stdlib/"))
                packageListUrl.set(
                        file("stdlib.package.list").toURL()
                )
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set([Visibility.PUBLIC])
            }
        }
    }
}

Последнее изменение: 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-gradle.html