Командная строка (CLI)

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

{
  "moduleName": "Dokka Example",
  "moduleVersion": null,
  "outputDir": "./build/dokka/html",
  "failOnWarning": false,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": false,
  "offlineMode": false,
  "includes": [
    "module.md"
  ],
  "sourceLinks":  [
    { "_comment": "Options are described in a separate section" }
  ],
  "perPackageOptions": [
    { "_comment": "Options are described in a separate section" }
  ],
  "externalDocumentationLinks":  [
    { "_comment": "Options are described in a separate section" }
  ],
  "sourceSets": [
    { "_comment": "Options are described in a separate section" }
  ],
  "pluginsClasspath": [
    "./dokka-base-1.8.20.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./dokka-analysis-1.8.20.jar",
    "./kotlin-analysis-intellij-1.8.20.jar",
    "./kotlin-analysis-compiler-1.8.20.jar",
    "./freemarker-2.3.31.jar"
  ]
}

moduleName

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

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

moduleVersion

Версия модуля.

По умолчанию: пустая

outputDirectory

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

По умолчанию: ./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

includes

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

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

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

sourceSets

Индивидуальная и дополнительная настройка наборов исходных кодов Kotlin source sets.

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

sourceLinks

Глобальная настройка ссылок на исходные коды, применяемая для всех наборов исходных кодов.

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

perPackageOptions

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

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

externalDocumentationLinks

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

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

pluginsClasspath

Список JAR-файлов с плагинами Dokka и их зависимостями.

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

Как настроить наборы исходных файлов Kotlin source sets:

{
  "sourceSets": [
    {
      "displayName": "jvm",
      "sourceSetID": {
        "scopeId": "moduleName",
        "sourceSetName": "main"
      },
      "dependentSourceSets": [
        {
          "scopeId": "dependentSourceSetScopeId",
          "sourceSetName": "dependentSourceSetName"
        }
      ],
      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"],
      "reportUndocumented": false,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 8,
      "languageVersion": "1.7",
      "apiVersion": "1.7",
      "noStdlibLink": false,
      "noJdkLink": false,
      "includes": [
        "module.md"
      ],
      "analysisPlatform": "jvm",
      "sourceRoots": [
        "/home/ignat/IdeaProjects/dokka-debug-mvn/src/main/kotlin"
      ],
      "classpath": [
        "libs/kotlin-stdlib-1.9.0.jar",
        "libs/kotlin-stdlib-common-1.9.0.jar"
      ],
      "samples": [
        "samples/basic.kt"
      ],
      "suppressedFiles": [
        "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
      ],
      "sourceLinks":  [
        { "_comment": "Options are described in a separate section" }
      ],
      "perPackageOptions": [
        { "_comment": "Options are described in a separate section" }
      ],
      "externalDocumentationLinks":  [
        { "_comment": "Options are described in a separate section" }
      ]
    }
  ]
}

displayName

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

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

Имя платформы можно использовать, если нет лучшей альтернативы.

sourceSetID

Технический идентификатор набора исходных файлов

documentedVisibilities

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

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

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

Возможные значения:

• PUBLIC

• PRIVATE

• PROTECTED

• INTERNAL

• PACKAGE

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

reportUndocumented

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

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

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

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

skipEmptyPackages

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

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

По умолчанию для исполнителя CLI: false.

skipDeprecated

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

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

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

jdkVersion

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

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

languageVersion

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

apiVersion

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

noStdlibLink

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

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

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

noJdkLink

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

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

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

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

includes

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

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

analysisPlatform

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

Возможные значения:

• jvm

• common

• js

• native

sourceRoots

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

classpath

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

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

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

samples

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

suppressedFiles

Файлы, которые нужно подавить при генерации документации.

sourceLinks

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

Список возможных параметров см. в разделе настройка ссылок на исходный код.

perPackageOptions

Набор параметров, специфичных для соответствующих пакетов в этом наборе исходных файлов.

Список возможных параметров см. в разделе настройка для каждого пакета.

externalDocumentationLinks

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

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

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

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

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

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

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

{
  "sourceLinks": [
    {
      "localDirectory": "src/main/kotlin",
      "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
      "remoteLineSuffix": "#L"
    }
  ]
}

localDirectory

Путь к локальному каталогу с исходным кодом.

remoteUrl

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

remoteLineSuffix

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

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

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

• GitHub: #L

• GitLab: #L

• Bitbucket: #lines-

По умолчанию: пустая строка (без суффикса)

Настройка по пакетам

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

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

{
  "perPackageOptions": [
    {
      "matchingRegex": ".*internal.*",
      "suppress": false,
      "skipDeprecated": false,
      "reportUndocumented": false,
      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
    }
  ]
}

matchingRegex

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

suppress

Указывает, следует ли пропускать этот пакет при генерации документации.

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

skipDeprecated

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

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

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

reportUndocumented

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

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

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

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

documentedVisibilities

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

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

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

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

Настройка внешних ссылок на документацию

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

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

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

{
  "externalDocumentationLinks": [
    {
      "url": "https://kotlinlang.org/api/kotlinx.serialization/",
      "packageListUrl": "https://kotlinlang.org/api/kotlinx.serialization/package-list"
    }
  ]
}

url

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

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

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

packageListUrl

Точное местоположение package-list. Это альтернатива, чтобы не полагаться на автоматическое разрешение Dokka.

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

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

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

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

{
  "moduleName": "Dokka Example",
  "moduleVersion": null,
  "outputDir": "./build/dokka/html",
  "failOnWarning": false,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": false,
  "offlineMode": false,
  "sourceLinks": [
    {
      "localDirectory": "src/main/kotlin",
      "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
      "remoteLineSuffix": "#L"
    }
  ],
  "externalDocumentationLinks": [
    {
      "url": "https://docs.oracle.com/javase/8/docs/api/",
      "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
    },
    {
      "url": "https://kotlinlang.org/api/latest/jvm/stdlib/",
      "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list"
    }
  ],
  "perPackageOptions": [
    {
      "matchingRegex": ".*internal.*",
      "suppress": false,
      "reportUndocumented": false,
      "skipDeprecated": false,
      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
    }
  ],
  "sourceSets": [
    {
      "displayName": "jvm",
      "sourceSetID": {
        "scopeId": "moduleName",
        "sourceSetName": "main"
      },
      "dependentSourceSets": [
        {
          "scopeId": "dependentSourceSetScopeId",
          "sourceSetName": "dependentSourceSetName"
        }
      ],
      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"],
      "reportUndocumented": false,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 8,
      "languageVersion": "1.7",
      "apiVersion": "1.7",
      "noStdlibLink": false,
      "noJdkLink": false,
      "includes": [
        "module.md"
      ],
      "analysisPlatform": "jvm",
      "sourceRoots": [
        "/home/ignat/IdeaProjects/dokka-debug-mvn/src/main/kotlin"
      ],
      "classpath": [
        "libs/kotlin-stdlib-1.9.0.jar",
        "libs/kotlin-stdlib-common-1.9.0.jar"
      ],
      "samples": [
        "samples/basic.kt"
      ],
      "suppressedFiles": [
        "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
      ],
      "sourceLinks": [
        {
          "localDirectory": "src/main/kotlin",
          "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
          "remoteLineSuffix": "#L"
        }
      ],
      "externalDocumentationLinks": [
        {
          "url": "https://docs.oracle.com/javase/8/docs/api/",
          "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
        },
        {
          "url": "https://kotlinlang.org/api/latest/jvm/stdlib/",
          "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list"
        }
      ],
      "perPackageOptions": [
        {
          "matchingRegex": ".*internal.*",
          "suppress": false,
          "reportUndocumented": false,
          "skipDeprecated": false,
          "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
        }
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka-base-1.8.20.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./dokka-analysis-1.8.20.jar",
    "./kotlin-analysis-intellij-1.8.20.jar",
    "./kotlin-analysis-compiler-1.8.20.jar",
    "./freemarker-2.3.31.jar"
  ],
  "pluginsConfiguration": [
    {
      "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
      "serializationFormat": "JSON",
      "values": "{\"separateInheritedMembers\":false,\"footerMessage\":\"© 2021 pretty good Copyright\"}"
    }
  ],
  "includes": [
    "module.md"
  ]
}