CLI

Предварительные требования

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

Ниже перечислены зависимости, необходимые для любого формата вывода:

Ниже перечислены дополнительные зависимости, необходимые для формата вывода HTML:

Запуск с параметрами командной строки

Для настройки средства запуска CLI можно передавать параметры командной строки.

Как минимум необходимо указать следующие параметры:

• -pluginsClasspath — список абсолютных или относительных путей к скачанным зависимостям, разделённых точками с запятой ;

• -sourceSet — абсолютный путь к исходному коду, для которого нужно сгенерировать документацию

• -outputDir — абсолютный или относительный путь к каталогу для вывода документации

java -jar dokka-cli-2.2.0.jar \
     -pluginsClasspath "./dokka-base-2.2.0.jar;./analysis-kotlin-symbols-2.2.0.jar;./kotlinx-html-jvm-0.8.0.jar;./freemarker-2.3.31.jar" \
     -sourceSet "-src /home/myCoolProject/src/main/kotlin" \
     -outputDir "./dokka/html"

При выполнении приведённого примера документация будет сгенерирована в формате вывода HTML.

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

Запуск с конфигурацией JSON

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

java -jar dokka-cli-2.2.0.jar dokka-configuration.json

Как минимум необходим следующий файл конфигурации JSON:

{
  "outputDir": "./dokka/html",
  "sourceSets": [
    {
      "sourceSetID": {
        "scopeId": "moduleName",
        "sourceSetName": "main"
      },
      "sourceRoots": [
        "/home/myCoolProject/src/main/kotlin"
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka-base-2.2.0.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./analysis-kotlin-symbols-2.2.0.jar",
    "./freemarker-2.3.31.jar"
  ]
}

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

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

По умолчанию артефакт dokka-base содержит только формат вывода HTML.

Все остальные форматы вывода реализованы как плагины Dokka. Чтобы использовать их, необходимо добавить их в classpath плагинов.

Например, если вы хотите сгенерировать документацию в экспериментальном формате вывода GFM, необходимо скачать JAR-файл плагина gfm (скачать) и передать его в параметр конфигурации pluginsClasspath.

С помощью параметров командной строки:

java -jar dokka-cli-2.2.0.jar \
     -pluginsClasspath "./dokka-base-2.2.0.jar;...;./gfm-plugin-2.2.0.jar" \
     ...

С помощью конфигурации JSON:

{
  ...
  "pluginsClasspath": [
    "./dokka-base-2.2.0.jar",
    "...",
    "./gfm-plugin-2.2.0.jar"
  ],
  ...
}

Если передать плагин GFM в pluginsClasspath, средство запуска CLI сгенерирует документацию в формате вывода GFM.

Дополнительные сведения см. на страницах GFM и Javadoc.

Параметры набора исходного кода

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

java -jar dokka-cli-2.2.0.jar -sourceSet -help

Краткое описание:

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

{
  "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-2.2.0.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./analysis-kotlin-symbols-2.2.0.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.

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

sourceLinks

Общая конфигурация ссылок на исходный код, применяемая ко всем наборам исходных файлов.

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

perPackageOptions

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

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

externalDocumentationLinks

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

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

pluginsClasspath

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

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

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

{
  "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-2.4.20.jar",
        "libs/kotlin-stdlib-common-2.4.20.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

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

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

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

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

skipEmptyPackages

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

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

Значение по умолчанию для CLI runner: false.

skipDeprecated

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

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

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

jdkVersion

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

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

languageVersion

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

apiVersion

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

noStdlibLink

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

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

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

noJdkLink

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

Версия документации Javadoc для JDK определяется параметром jdkVersion.

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

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

includes

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

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

analysisPlatform

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

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

• jvm

• common

• js

• native

sourceRoots

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

classpath

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

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

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

samples

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

suppressedFiles

Файлы, которые следует исключить при создании документации.

suppressAnnotatedWith

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

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

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

Следует ли выдавать предупреждения о видимых объявлениях без документации, то есть объявлениях без KDoc, после их фильтрации с помощью 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,
  "suppressAnnotatedWith": [
    "com.example.SuppressMe"
  ],
  "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/core/kotlin-stdlib/",
      "packageListUrl": "https://kotlinlang.org/api/core/kotlin-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-2.4.20.jar",
        "libs/kotlin-stdlib-common-2.4.20.jar"
      ],
      "samples": [
        "samples/basic.kt"
      ],
      "suppressedFiles": [
        "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
      ],
      "suppressAnnotatedWith": [
        "com.example.SuppressMe"
      ],
      "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/core/kotlin-stdlib/",
          "packageListUrl": "https://kotlinlang.org/api/core/kotlin-stdlib/package-list"
        }
      ],
      "perPackageOptions": [
        {
          "matchingRegex": ".*internal.*",
          "suppress": false,
          "reportUndocumented": false,
          "skipDeprecated": false,
          "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
        }
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka-base-2.2.0.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./analysis-kotlin-symbols-2.2.0.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"
  ]
}