From 2c17ae0e0af4106df89411fefd3c85904684d1c7 Mon Sep 17 00:00:00 2001 From: IgnatBeresnev Date: Thu, 22 Dec 2022 05:57:51 +0100 Subject: [PATCH] Fix review comments and proofread documentation once more --- CONTRIBUTING.md | 2 +- docs/README.md | 95 +---- docs/dokka.tree | 8 +- ...ugins_introduction.md => dokka_plugins.md} | 26 +- docs/topics/formats/html.md | 45 +-- docs/topics/formats/javadoc.md | 18 +- docs/topics/formats/markdown.md | 26 +- docs/topics/get_started.md | 95 +++++ docs/topics/overview.md | 98 +----- docs/topics/plugins/versioning.md | 327 ------------------ docs/topics/runners/cli.md | 200 ++++++----- docs/topics/runners/gradle.md | 271 ++++++++------- docs/topics/runners/maven.md | 168 +++++---- examples/maven/pom.xml | 2 +- .../dokka/gradle/GradleSourceLinkBuilder.kt | 4 +- .../src/main/kotlin/SourceLinkMapItem.kt | 8 +- 16 files changed, 528 insertions(+), 865 deletions(-) rename docs/topics/{plugins/plugins_introduction.md => dokka_plugins.md} (88%) create mode 100644 docs/topics/get_started.md delete mode 100644 docs/topics/plugins/versioning.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92bc91051f..ca58ff4de0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ Here's how to import and configure Dokka in IntelliJ IDEA: If you want to use/test your locally built Dokka in a project, do the following: 1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version. - For instance, you can set it to something like `1.7.20-my-fix-SNAPSHOT`. + For example, you can set it to something like `1.7.20-my-fix-SNAPSHOT`. 2. Publish it to maven local (`./gradlew publishToMavenLocal`) 3. In the project you want to generate documentation for, add maven local as a plugin/dependency repository (`mavenLocal()`) diff --git a/docs/README.md b/docs/README.md index 0683b80748..686c95bd30 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,95 +2,8 @@ This folder contains the Dokka documentation that is available on [kotlinlang.org](https://kotlinlang.org/). -Our documentation is written in Markdown format with some domain specific language (DSL) that is used at JetBrains. +Our documentation is written in Markdown format with some domain specific language (DSL) constructs that are used at +JetBrains. -## Project structure - -This project contains: -* A `topics` directory, which contains our documentation in Markdown format. -* A `dokka.tree` file, that describes the site navigation structure. -* A `vars.list` file, that contains a list of variables that you can use throughout documentation. - -## DSL guide - -This section explains what DSL you can use to create different document elements. - -### Title - -To declare the title of your document: - -```text -[//]: # (title: Name of topic) -``` - -Every document must have a title. By default, this title is used in the side menu. - -As the title is a level 1 header, it must be the only level 1 header in your document. All other headers within your document must be at least level 2, otherwise the side menu may not work as expected. - -### Notes - -To add a note: - -```text -> This is a simple note -> -{type="note"} -``` - -### Tips - -To add a tip: - -```text -> This is a useful tip -> -{type="tip"} -``` - -### Warning - -To add a warning: - -```text -> This is a warning -> -{type="warning"} -``` - -### Tabs - -Tabs can be used to save space in your document, allowing you to show different text in the same space depending on the tab chosen. - -Content within tabs isn't limited to text. You can also add code blocks, tips, etc. - -```text - - - -Instructions specific to Kotlin - - - -Instructions specific to Groovy - - - -Instructions specific to Maven - - - -Instructions specific to CLI - - - -``` - -You can use the `group-key` parameter to link tabs in a document together. Grouping tabs like this means that if your reader selects a particular tab, e.g. "Groovy", then other tabbed sections in your document will also show the tab for "Groovy" first. - -## Documentation preview - -Unfortunately, at the moment, to properly preview documentation you need to be a JetBrains employee -or have access to internal infrastructure. - -If you do have access, download `Stardust` plugin (ask around for instructions), and on the right sidebar you'll see -`Stardust Article Preview` tab, open it. +If you wish to contribute to the documentation, please read through +[Kotlin documentation guidelines](https://docs.google.com/document/d/1mUuxK4xwzs3jtDGoJ5_zwYLaSEl13g_SuhODdFuh2Dc/edit). diff --git a/docs/dokka.tree b/docs/dokka.tree index eb1da12d24..db1a933e9a 100644 --- a/docs/dokka.tree +++ b/docs/dokka.tree @@ -7,7 +7,8 @@ start-page="quickstart.md"> - + + @@ -17,8 +18,5 @@ - - - - + diff --git a/docs/topics/plugins/plugins_introduction.md b/docs/topics/dokka_plugins.md similarity index 88% rename from docs/topics/plugins/plugins_introduction.md rename to docs/topics/dokka_plugins.md index bee4c02729..06dbcdf03c 100644 --- a/docs/topics/plugins/plugins_introduction.md +++ b/docs/topics/dokka_plugins.md @@ -30,7 +30,7 @@ to your project: -The Gradle plugin creates convenient dependency configurations that allow you to apply plugins universally or +The Dokka Gradle runner creates convenient dependency configurations that allow you to apply plugins universally or for a specific output format only. ```kotlin @@ -54,7 +54,7 @@ dependencies { -The Gradle plugin creates convenient dependency configurations that allow you to apply Dokka plugins universally or +The Dokka Gradle runner creates convenient dependency configurations that allow you to apply Dokka plugins universally or for a specific output format only. ```groovy @@ -98,7 +98,7 @@ dependencies { -If you are using the [CLI](cli.md) runner with [command line arguments](cli.md#running-with-command-line-arguments), +If you are using the [CLI](cli.md) runner with [command line options](cli.md#running-with-command-line-options), Dokka plugins should be passed as `.jar` files to `-pluginsClasspath`: ```Shell @@ -127,18 +127,18 @@ If you are using [JSON configuration](cli.md#running-with-json-configuration), D ## Configuring Dokka plugins -Dokka plugins can also have configuration options of their own. Consult each plugin's documentation to see which -options are available. +Dokka plugins can also have configuration options of their own. To see which options are available, consult +documentation of the plugin you want to configure. Let's have a look at how you can configure the `DokkaBase` plugin, which is responsible for generating [HTML](html.md) -documentation, by adding a custom image to assets (`customAssets` option), by adding custom style sheets +documentation, by adding a custom image to the assets (`customAssets` option), by adding custom style sheets (`customStyleSheets` option), and by modifying the footer message (`footerMessage` option): -Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding plugin's artifact to classpath -dependencies in the `buildscript` block, and then importing plugin and configuration classes: +Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding the plugin's artifact to +the classpath dependencies in the `buildscript` block, and then importing plugin and configuration classes: ```kotlin import org.jetbrains.dokka.base.DokkaBase @@ -232,8 +232,8 @@ tasks.withType(DokkaTask.class) { -If you are using the [CLI](cli.md) runner with [command line arguments](cli.md#running-with-command-line-arguments), -use the `-pluginsConfiguration` argument that accepts JSON configuration in the form of `fullyQualifiedPluginName=json`. +If you are using the [CLI](cli.md) runner with [command line options](cli.md#running-with-command-line-options), +use the `-pluginsConfiguration` option that accepts JSON configuration in the form of `fullyQualifiedPluginName=json`. If you need to configure multiple plugins, you can pass multiple values separated by `^^`. @@ -244,7 +244,7 @@ java -jar dokka-cli-%dokkaVersion%.jar \ ``` If you are using [JSON configuration](cli.md#running-with-json-configuration), there exists a similar -`pluginsConfiguration` array that accepts JSON as `values`. +`pluginsConfiguration` array that accepts JSON configuration in `values`. ```json { @@ -264,12 +264,10 @@ If you are using [JSON configuration](cli.md#running-with-json-configuration), t ## Notable plugins -For a list of popular Dokka plugins, see the table below. - | **Name** | **Description** | |-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------| | [Android documentation plugin](https://github.com/Kotlin/dokka/tree/master/plugins/android-documentation) | Improves the documentation experience on Android | -| [Versioning plugin](versioning.md) | Adds version selector and helps to organize documentation for different versions of your application/library | +| [Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) | Adds version selector and helps to organize documentation for different versions of your application/library | | [MermaidJS HTML plugin](https://github.com/glureau/dokka-mermaid) | Renders [MermaidJS](https://mermaid-js.github.io/mermaid/#/) diagrams and visualizations found in KDocs | | [Mathjax HTML plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) | Pretty prints mathematics found in KDocs | | [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) | Renders Kotlin signatures as seen from Java's perspective | diff --git a/docs/topics/formats/html.md b/docs/topics/formats/html.md index 4b1e1d8a26..f4fbdb2c9d 100644 --- a/docs/topics/formats/html.md +++ b/docs/topics/formats/html.md @@ -10,7 +10,7 @@ HTML as an output format is supported by all runners. To generate HTML documenta * For [Maven](maven.md#generating-documentation), run the `dokka:dokka` goal. * For [CLI runner](cli.md#generating-documentation), run with HTML dependencies set. -> HTML pages generated by this format require a web server in order to render everything correctly. +> HTML pages generated by this format need to be hosted on a web server in order to render everything correctly. > > You can use any free static site hosting service, such as > [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages). @@ -133,7 +133,7 @@ tasks.withType(DokkaTask.class) { -Via [command line arguments](cli.md#running-with-command-line-arguments): +Via [command line options](cli.md#running-with-command-line-options): ```Bash java -jar dokka-cli-%dokkaVersion%.jar \ @@ -164,16 +164,16 @@ Via [JSON configuration](cli.md#running-with-json-configuration): The table below contains all of the possible configuration options and their purpose. -| **Option** | **Description** | -|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `customAssets` | List of paths for image assets to be bundled with documentation. The image assets can have any file extension. For more information, see [Customizing assets](#customizing-assets). | -| `customStyleSheets` | List of paths for `.css` stylesheets to be bundled with documentation and used for rendering. For more information, see [Customizing styles](#customizing-styles). | -| `templatesDir` | Path to the directory containing custom HTML templates. For more information, see [Templates](#templates). | -| `footerMessage` | The text displayed in the footer. | -| `separateInheritedMembers` | This is a boolean property. If set to `true`, Dokka renders properties/functions and inherited properties/inherited functions separately. This is disabled by default. | -| `mergeImplicitExpectActualDeclarations` | This is a boolean property. If set to true, Dokka merges declarations that are not declared as [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html), but have the same fully qualified name. This can be useful for legacy codebases. This is disabled by default. | +| **Option** | **Description** | +|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `customAssets` | List of paths for image assets to be bundled with documentation. The image assets can have any file extension. For more information, see [Customizing assets](#customizing-assets). | +| `customStyleSheets` | List of paths for `.css` stylesheets to be bundled with documentation and used for rendering. For more information, see [Customizing styles](#customizing-styles). | +| `templatesDir` | Path to the directory containing custom HTML templates. For more information, see [Templates](#templates). | +| `footerMessage` | The text displayed in the footer. | +| `separateInheritedMembers` | This is a boolean option. If set to `true`, Dokka renders properties/functions and inherited properties/inherited functions separately. This is disabled by default. | +| `mergeImplicitExpectActualDeclarations` | This is a boolean option. If set to `true`, Dokka merges declarations that are not declared as [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html), but have the same fully qualified name. This can be useful for legacy codebases. This is disabled by default. | -For more information about configuring Dokka plugins, see [Configuring Dokka plugins](plugins_introduction.md#configuring-dokka-plugins). +For more information about configuring Dokka plugins, see [Configuring Dokka plugins](dokka_plugins.md#configuring-dokka-plugins). ## Customization @@ -184,7 +184,7 @@ To help you add your own look and feel to your documentation, the HTML format su You can use your own stylesheets by using the `customStyleSheets` [configuration option](#configuration). These are applied to every page. -It's also possible to override Dokka's stylesheets by using files with the same name: +It's also possible to override Dokka's default stylesheets by providing files with the same name: | **Stylesheet name** | **Description** | |----------------------|--------------------------------------------------------------------| @@ -199,9 +199,11 @@ The source code for all of Dokka's stylesheets is ### Customizing assets You can provide your own images to be bundled with documentation by using the `customAssets` -[configuration option](#configuration). These files are copied to the `/images` directory. +[configuration option](#configuration). -It's possible to override Dokka's images and icons by using files with the same name. The most +These files are copied to the `/images` directory. + +It's possible to override Dokka's images and icons by providing files with the same name. The most useful and relevant one being `logo-icon.svg`, which is the image that's used in the header. The rest is mostly icons. You can find all images used by Dokka on @@ -209,10 +211,11 @@ You can find all images used by Dokka on ### Changing the logo -To customize the logo, you can begin by [providing your own asset](#customizing-assets) for `logo-icon.svg`. For the best results, use an image of a similar size. +To customize the logo, you can begin by [providing your own asset](#customizing-assets) for `logo-icon.svg`. +If your image has similar size, it should not look out of place. However, if your image has different dimensions or you want to use a `.png` file instead of the default `.svg` file, -you can [override the `logo-styles.css` stylesheet](#customizing-styles) to make it fit. +you can [override the `logo-styles.css` stylesheet](#customizing-styles) and make it fit. For an example of how to do this, see our [custom format example project](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle/dokka-customFormat-example). @@ -270,9 +273,9 @@ context and thus they need to be resolved at later stages by the [MultiModule](g You can also use the following Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html): -| **Variable** | **Description** | -|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| `<@content/>` | The main page content. | -| `<@resources/>` | Resources such as scripts and stylesheets. | -| `<@version/>` | The module version taken from configuration. If the [versioning plugin](versioning.md) is applied, it is replaced with a version navigator. | +| **Variable** | **Description** | +|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `<@content/>` | The main page content. | +| `<@resources/>` | Resources such as scripts and stylesheets. | +| `<@version/>` | The module version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) is applied, it is replaced with a version navigator. | diff --git a/docs/topics/formats/javadoc.md b/docs/topics/formats/javadoc.md index d85cb680ab..a5e6116d5d 100644 --- a/docs/topics/formats/javadoc.md +++ b/docs/topics/formats/javadoc.md @@ -5,7 +5,7 @@ > {type="warning"} -Dokka's Javadoc output format is similar to Java's +Dokka's Javadoc output format is a lookalike of Java's [Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). It tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation @@ -14,15 +14,15 @@ or an exact copy. ![Screenshot of javadoc output format](javadoc-format-example.png){height=750} All Kotlin code and signatures are rendered as seen from Java's perspective. This is achieved with our -[Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java), which comes bundled and +[Kotlin as Java Dokka plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java), which comes bundled and applied by default for this format. -The Javadoc output format is generated by our [Dokka plugin](plugins_introduction.md), which we actively maintain. +The Javadoc output format itself is a [Dokka plugin](dokka_plugins.md), and it is maintained by the Dokka team. It is open source and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc). ## Generating Javadoc documentation -> The Javadoc format is not supported for multiplatform projects. +> The Javadoc format does not support multiplatform projects. > {type="warning"} @@ -30,7 +30,7 @@ It is open source and you can find the source code on [GitHub](https://github.co -Dokka's [Gradle plugin](gradle.md) comes with the Javadoc output format included. You can use the following tasks: +Dokka's [Gradle runner](gradle.md) comes with the Javadoc output format included. You can use the following tasks: | **Task** | **Description** | |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -42,7 +42,7 @@ The `javadoc.jar` file can be generated separately. For more information, see [B -Dokka's [Maven plugin](maven.md) comes with the Javadoc output format built in. You can generate documentation +Dokka's [Maven runner](maven.md) comes with the Javadoc output format built in. You can generate documentation by using the following goals: | **Goal** | **Description** | @@ -54,15 +54,15 @@ by using the following goals: -Since the Javadoc output format is generated by a [Dokka plugin](plugins_introduction.md#applying-dokka-plugins), you need to download the plugin as a -[JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/javadoc-plugin/%dokkaVersion%). +Since the Javadoc output format is a [Dokka plugin](dokka_plugins.md#applying-dokka-plugins), you need to +download the plugin's [JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/javadoc-plugin/%dokkaVersion%). The Javadoc output format has two dependencies that you need to provide as additional JAR files: * [kotlin-as-java plugin](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin/%dokkaVersion%) * [korte-jvm](https://mvnrepository.com/artifact/com.soywiz.korlibs.korte/korte-jvm/3.3.0) -Via [command line arguments](cli.md#running-with-command-line-arguments): +Via [command line options](cli.md#running-with-command-line-options): ```Bash java -jar dokka-cli-%dokkaVersion%.jar \ diff --git a/docs/topics/formats/markdown.md b/docs/topics/formats/markdown.md index 690cfbb156..fb7ed094ca 100644 --- a/docs/topics/formats/markdown.md +++ b/docs/topics/formats/markdown.md @@ -10,7 +10,7 @@ These formats give you more freedom in terms of hosting documentation as the out documentation website. For example, see [OkHttp's API reference](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) pages. -Markdown output formats are rendering [Dokka plugins](plugins_introduction.md), maintained by the Dokka team, and +Markdown output formats are rendering [Dokka plugins](dokka_plugins.md), maintained by the Dokka team, and they are open source. ## GFM @@ -20,7 +20,7 @@ The GFM output format generates documentation in [GitHub Flavored Markdown](http -Dokka's [Gradle plugin](gradle.md) comes with the GFM output format included. You can use the following tasks with it: +Dokka's [Gradle runner](gradle.md) comes with the GFM output format included. You can use the following tasks with it: | **Task** | **Description** | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -31,7 +31,7 @@ Dokka's [Gradle plugin](gradle.md) comes with the GFM output format included. Yo -Since GFM format is a [Dokka plugin](plugins_introduction.md#applying-dokka-plugins), you need to apply it as a plugin +Since GFM format is a [Dokka plugin](dokka_plugins.md#applying-dokka-plugins), you need to apply it as a plugin dependency: ```xml @@ -58,11 +58,11 @@ For more information, see the Mavin plugin documentation for [Other output forma -Since GFM format is a [Dokka plugin](plugins_introduction.md#applying-dokka-plugins), you need to download the -[jar file](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin/%dokkaVersion%) and pass it to +Since GFM format is a [Dokka plugin](dokka_plugins.md#applying-dokka-plugins), you need to download the +[JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin/%dokkaVersion%) and pass it to `pluginsClasspath`. -Via [command line arguments](cli.md#running-with-command-line-arguments): +Via [command line options](cli.md#running-with-command-line-options): ```Bash java -jar dokka-cli-%dokkaVersion%.jar \ @@ -98,7 +98,7 @@ The Jekyll output format generates documentation in [Jekyll](https://jekyllrb.co -Dokka's [Gradle plugin](gradle.md) comes with the Jekyll output format included. You can use the following tasks with it: +Dokka's [Gradle runner](gradle.md) comes with the Jekyll output format included. You can use the following tasks with it: | **Task** | **Description** | |--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -109,7 +109,7 @@ Dokka's [Gradle plugin](gradle.md) comes with the Jekyll output format included. -Since Jekyll format is a [Dokka plugin](plugins_introduction.md#applying-dokka-plugins), you need to apply it as a plugin +Since Jekyll format is a [Dokka plugin](dokka_plugins.md#applying-dokka-plugins), you need to apply it as a plugin dependency: ```xml @@ -131,17 +131,17 @@ dependency: After configuring this, running the `dokka:dokka` goal produces documentation in GFM format. -For more information, see the Maven plugin documentation for [Other output formats](maven.md#other-output-formats). +For more information, see the Maven runner documentation for [Other output formats](maven.md#other-output-formats). -Since Jekyll format is a [Dokka plugin](plugins_introduction.md#applying-dokka-plugins), you need to download the -[jar file](https://mvnrepository.com/artifact/org.jetbrains.dokka/jekyll-plugin/%dokkaVersion%). This format is also -based on [GFM](#gfm) format, so you need to provide it as a dependency as well. Both jars need to be passed to +Since Jekyll format is a [Dokka plugin](dokka_plugins.md#applying-dokka-plugins), you need to download the +[JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/jekyll-plugin/%dokkaVersion%). This format is also +based on [GFM](#gfm) format, so you need to provide it as a dependency as well. Both JARs need to be passed to `pluginsClasspath`: -Via [command line arguments](cli.md#running-with-command-line-arguments): +Via [command line options](cli.md#running-with-command-line-options): ```Bash java -jar dokka-cli-%dokkaVersion%.jar \ diff --git a/docs/topics/get_started.md b/docs/topics/get_started.md new file mode 100644 index 0000000000..1eb743a5d0 --- /dev/null +++ b/docs/topics/get_started.md @@ -0,0 +1,95 @@ +[//]: # (title: Get started) + +TODO add an introduction of some sort? + + + + +Apply the Dokka Gradle plugin in the root build script of your project: + +```kotlin +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} +``` + +When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need +to apply the Dokka Gradle plugin within subprojects as well: + +```kotlin +subprojects { + apply(plugin = "org.jetbrains.dokka") +} +``` + +To generate documentation, run the following Gradle tasks: + +* `dokkaHtml` for single-project builds +* `dokkaHtmlMultiModule` for multi-project builds + +By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. + +To learn more about Gradle configuration, see [Gradle](gradle.md). + + + + +Apply the Dokka Gradle plugin in the root build script of your project: + +```groovy +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} +``` + +When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need +to apply the Dokka Gradle plugin within subprojects as well: + +```groovy +subprojects { + apply plugin: 'org.jetbrains.dokka' +} +``` + +To generate documentation, run the following Gradle tasks: + +* `dokkaHtml` for single-project builds +* `dokkaHtmlMultiModule` for multi-project builds + +By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. + +To learn more about Gradle configuration, see [Gradle](gradle.md). + + + + +Add the Dokka Maven plugin to the `plugins` section of your POM file: + +```xml + + + + org.jetbrains.dokka + dokka-maven-plugin + %dokkaVersion% + + + pre-site + + dokka + + + + + + +``` + +To generate documentation, run the `dokka:dokka` goal. + +By default, the output directory is set to `target/dokka`. + +To learn more about Maven configuration, see [Maven](maven.md). + + + diff --git a/docs/topics/overview.md b/docs/topics/overview.md index 8321fe2028..d52a636e92 100644 --- a/docs/topics/overview.md +++ b/docs/topics/overview.md @@ -9,7 +9,7 @@ Just like Kotlin itself, Dokka supports mixed-language projects. It understands Dokka can generate documentation in multiple formats, including its own modern [HTML format](html.md), multiple flavors of [Markdown](markdown.md), and Java's [Javadoc HTML](javadoc.md). -There are already a number of libraries that use Dokka for their API reference documentation: +Some libraries that use Dokka for their API reference documentation: * [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/) * [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html) @@ -17,100 +17,8 @@ There are already a number of libraries that use Dokka for their API reference d * [Ktor](https://api.ktor.io/) * [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown) -Dokka can be run via [Gradle](gradle.md), [Maven](maven.md) or on the [command line](cli.md). It is also -[highly pluggable](plugins_introduction.md). - -## Quickstart - - - - -Apply the Dokka Gradle plugin in the root of your project: - -```kotlin -plugins { - id("org.jetbrains.dokka") version "%dokkaVersion%" -} -``` - -When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply the Dokka plugin within subprojects as well: - -```kotlin -subprojects { - apply(plugin = "org.jetbrains.dokka") -} -``` - -To generate documentation, run the following Gradle tasks: - -* `dokkaHtml` for single-project builds -* `dokkaHtmlMultiModule` for multi-module builds - -By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. - -To learn more about Gradle configuration, see [Gradle](gradle.md). - - - - -Apply the Dokka Gradle plugin in the root of your project: - -```groovy -plugins { - id 'org.jetbrains.dokka' version '%dokkaVersion%' -} -``` - -When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply the Dokka plugin within subprojects as well: - -```groovy -subprojects { - apply plugin: 'org.jetbrains.dokka' -} -``` - -To generate documentation, run the following Gradle tasks: - -* `dokkaHtml` for single-project builds -* `dokkaHtmlMultiModule` for multi-module builds - -By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. - -To learn more about Gradle configuration, see [Gradle](gradle.md). - - - - -Add the Dokka Maven plugin to the plugins section of your POM file: - -```xml - - - - org.jetbrains.dokka - dokka-maven-plugin - %dokkaVersion% - - - pre-site - - dokka - - - - - - -``` - -To generate documentation, run the `dokka:dokka` goal. - -By default, the output directory is set to `target/dokka`. - -To learn more about Maven configuration, see [Maven](maven.md). - - - +You can run Dokka using [Gradle](gradle.md), [Maven](maven.md) or from the [command line](cli.md). It is also +[highly pluggable](dokka_plugins.md). ## Community diff --git a/docs/topics/plugins/versioning.md b/docs/topics/plugins/versioning.md deleted file mode 100644 index f0d4be0a7d..0000000000 --- a/docs/topics/plugins/versioning.md +++ /dev/null @@ -1,327 +0,0 @@ -[//]: # (title: Versioning plugin) - -The versioning plugin provides the ability to host documentation for multiple versions of your library/application -with seamless switching between them. This, in turn, provides a better experience for your users. - -![Screenshot of documentation version dropdown](versioning-plugin-example.png){height=350} - -> The versioning plugin only works with [HTML](html.md) format. -> -{type="note"} - -Visit the [versioning plugin example project](https://github.com/Kotlin/dokka/tree/1.7.20/examples/gradle/dokka-versioning-multimodule-example) -to see an example of it in action and how it can be configured. - -## Applying the plugin - -You can apply the versioning plugin the same way as other [Dokka plugins](plugins_introduction.md#applying-dokka-plugins): - - - - -```kotlin -dependencies { - dokkaHtmlPlugin("org.jetbrains.dokka:versioning-plugin:%dokkaVersion%") -} -``` - -> When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply the versioning plugin within -> subprojects as well as in their parent project. -> -{type="note"} - - - - -```groovy -dependencies { - dokkaHtmlPlugin 'org.jetbrains.dokka:versioning-plugin:%dokkaVersion%' -} -``` - -> When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply the versioning plugin within -> subprojects as well as in their parent project. -> -{type="note"} - - - - -```xml - - org.jetbrains.dokka - dokka-maven-plugin - ... - - - - org.jetbrains.dokka - versioning-plugin - %dokkaVersion% - - - - -``` - - - - -You can find the versioning plugin's artifact on -[mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/versioning-plugin/%dokkaVersion%) or by browsing -[maven central repository](https://repo1.maven.org/maven2/org/jetbrains/dokka/versioning-plugin/%dokkaVersion%/) -directly, and pass it to `pluginsClasspath`. - -Via [command line arguments](cli.md#running-with-command-line-arguments): - -```Bash -java -jar dokka-cli-%dokkaVersion%.jar \ - -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./versioning-plugin-%dokkaVersion%.jar" \ - ... -``` - -Via [JSON configuration](cli.md#running-with-json-configuration): - -```json -{ - ... - "pluginsClasspath": [ - "./dokka-base-%dokkaVersion%.jar", - "...", - "./versioning-plugin-%dokkaVersion%.jar" - ], - ... -} -``` - - - - -## Configuration - -### Configuration options - -The table below contains all the possible configuration options for the versioning plugin and their purpose. - -| **Option** | **Description** | -|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `version` | The version of your application/library that documentation is going to be generated for. This will be the version shown in the dropdown menu. | -| `versionsOrdering` | An optional list of strings that represents the order that versions should appear in the dropdown menu. Must match versions string exactly. The first item in the list is at the top of the dropdown. | -| `olderVersionsDir` | An optional path to a parent folder that contains other documentation versions. It requires a specific directory structure. For more information, see [Directory structure](#directory-structure). | -| `olderVersions` | An optional list of paths to other documentation versions. It must point to Dokka's outputs directly. This is useful if different versions can't all be in the same directory. | -| `renderVersionsNavigationOnAllPages` | An optional boolean value indicating whether to render the navigation dropdown on all pages. Set to true by default. | - -#### Directory structure - -Note that the directory passed to `olderVersionsDir` needs to follow a specific structure: - -```text -. -└── olderVersionsDir - └── 1.7.10 - ├── - └── 1.7.20 - ├── -... -``` - -### Configuration example - - - - -```kotlin -import org.jetbrains.dokka.versioning.VersioningPlugin -import org.jetbrains.dokka.versioning.VersioningConfiguration - -buildscript { - dependencies { - classpath("org.jetbrains.dokka:versioning-plugin:%dokkaVersion%") - } -} - -tasks.dokkaHtml { - pluginConfiguration { - version = "1.5" - versionsOrdering = listOf("1.5", "1.4", "1.3", "1.2", "1.1", "alpha-2", "alpha-1") - olderVersionsDir = file("documentation/version") - olderVersions = listOf(file("documentation/alpha/alpha-2"), file("documentation/alpha/alpha-1")) - renderVersionsNavigationOnAllPages = true - } -} -``` - -Alternatively, you can configure it via JSON: - -```kotlin - val versioningConfiguration = """ - { - "version": "1.5", - "versionsOrdering": ["1.5", "1.4", "1.3", "1.2", "1.1", "alpha-2", "alpha-1"], - "olderVersionsDir": "documentation/version", - "olderVersions": ["documentation/alpha/alpha-2", "documentation/alpha/alpha-1"], - "renderVersionsNavigationOnAllPages": true - } - """ - pluginsMapConfiguration.set( - mapOf( - "org.jetbrains.dokka.versioning.VersioningPlugin" to versioningConfiguration - ) - ) -``` - - - - -```groovy -dokkaHtml { - String versioningConfiguration = """ - { - "version": "1.5", - "versionsOrdering": ["1.5", "1.4", "1.3", "1.2", "1.1", "alpha-2", "alpha-1"], - "olderVersionsDir": "documentation/version", - "olderVersions": ["documentation/alpha/alpha-2", "documentation/alpha/alpha-1"], - "renderVersionsNavigationOnAllPages": true - } - """ - pluginsMapConfiguration.set( - ["org.jetbrains.dokka.versioning.VersioningPlugin": versioningConfiguration] - ) -} -``` - - - - -```xml - - org.jetbrains.dokka - dokka-maven-plugin - ... - - - - 1.5 - - 1.5 - 1.4 - 1.3 - 1.2 - 1.1 - alpha-2 - alpha-1 - - ${project.basedir}/documentation/version - - ${project.basedir}/documentation/alpha/alpha-2 - ${project.basedir}/documentation/alpha/alpha-1 - - true - - - - -``` - - - - -```Bash -java -jar dokka-cli-%dokkaVersion%.jar \ - ... - -pluginsConfiguration "org.jetbrains.dokka.versioning.VersioningPlugin={\"version\": \"1.5\", \"versionsOrdering\": [\"1.5\", \"1.4\", \"1.3\", \"1.2\", \"1.1\", \"alpha-2\", \"alpha-1\"], \"olderVersionsDir\": \"documentation/version\", \"olderVersions\": [\"documentation/alpha/alpha-2\", \"documentation/alpha/alpha-1\"], \"renderVersionsNavigationOnAllPages\": true}" - -``` - -Alternatively, via JSON configuration: -```json -{ - "moduleName": "Dokka Example", - ... - "pluginsConfiguration": [ - { - "fqPluginName": "org.jetbrains.dokka.versioning.VersioningPlugin", - "serializationFormat": "JSON", - "values": "{\"version\": \"1.5\", \"versionsOrdering\": [\"1.5\", \"1.4\", \"1.3\", \"1.2\", \"1.1\", \"alpha-2\", \"alpha-1\"], \"olderVersionsDir\": \"documentation/version\", \"olderVersions\": [\"documentation/alpha/alpha-2\", \"documentation/alpha/alpha-1\"], \"renderVersionsNavigationOnAllPages\": true}" - } - ] -} -``` - - - - -## Generating versioned documentation - -With the versioning plugin applied and configured, no other steps are needed. Documentation can be built in the usual way. - -Among other things, the versioning plugin adds a `version.json` file to the output folder. This file is used by the -plugin to match versions and generate version navigation. If your previously generated documentation does not have that -file, you will need to re-generate documentation for such versions. Just adding the file will not work. - -The versioning plugin also bundles all other documentation versions that have been passed through `olderVersionsDir` -and `olderVersions` configuration options by putting them inside the `older` directory. - -## Usage example - -There is no single correct way to configure the plugin, it can be tailored to your needs. However, -it can be a bit overwhelming when starting out. Below you will find one of the ways it can be configured so that you -can begin publishing versioned documentation straight away. - -The main idea behind it is the following: - -1. One directory contains all versions of your documentation. For example, `documentation/version/{doc_version}`. - This is your archive which is needed for future builds. -2. The output directory of all new builds is set to that directory as well, under `documentation/version/{new_version}`. -3. When new builds are executed, the plugin looks for previous versions of documentation in the archive directory. -4. Once new documentation has been generated, it needs to be **copied** to somewhere accessible by the user. - For example, GitHub pages or nginx static directories. It needs to be **copied**, not moved, because Dokka needs -5. Once it has been safely copied, you can remove the `older` directory from the newly generated and archived version. - This helps reduce the overhead of each version bundling all previous versions, as these files are effectively duplicates. - -```kotlin -import org.jetbrains.dokka.versioning.VersioningPlugin -import org.jetbrains.dokka.versioning.VersioningConfiguration - -buildscript { - dependencies { - classpath("org.jetbrains.dokka:versioning-plugin:%dokkaVersion%") - } -} - -dependencies { - dokkaPlugin("org.jetbrains.dokka:versioning-plugin:$dokkaVersion") -} - -tasks.dokkaHtml { - // This can be any persistent folder where - // you store documentation by version - val docVersionsDir = projectDir.resolve("documentation/version") - - // The version for which you are currently generating docs - val currentVersion = "1.3" - - // Set the output to a folder with all other versions - // as you'll need the current version for future builds - val currentDocsDir = docVersionsDir.resolve(currentVersion) - outputDirectory.set(currentDocsDir) - - pluginConfiguration { - olderVersionsDir = docVersionsDir - version = currentVersion - } - - doLast { - // This folder contains the latest documentation with all - // previous versions included, so it's ready to be published. - // Make sure it's copied and not moved - you'll still need this - // version for future builds - currentDocsDir.copyTo(file("/my/hosting")) - - // Only once current documentation has been safely moved, - // remove previous versions bundled in it. They will not - // be needed in future builds, it's just overhead. - currentDocsDir.resolve("older").deleteRecursively() - } -} -``` diff --git a/docs/topics/runners/cli.md b/docs/topics/runners/cli.md index cb7c72ca9d..e0ef7d3208 100644 --- a/docs/topics/runners/cli.md +++ b/docs/topics/runners/cli.md @@ -1,24 +1,26 @@ -[//]: # (title: CLI runner) +[//]: # (title: CLI) -If for some reason you cannot use [Gradle](gradle.md) or [Maven](maven.md) plugins, Dokka has -a command line (CLI) runner for generating documentation without any build tools. +If for some reason you cannot use [Gradle](gradle.md) or [Maven](maven.md) build tools, Dokka has +a command line (CLI) runner for generating documentation. -In comparison, it has the same, if not more, capabilities as the Gradle plugin. Although it is considerably more -difficult to set up as there is no autoconfiguration, especially in multiplatform and multimodule environments. - -The CLI runner is published as a separate artifact to Maven Central under `org.jetbrains.dokka:dokka-cli`, so you can -find it on [mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-cli) or by browsing -[maven central repository directories](https://repo1.maven.org/maven2/org/jetbrains/dokka/dokka-cli/) directly. +In comparison, it has the same, if not more, capabilities as the Gradle runner. Although it is considerably more +difficult to set up as there is no autoconfiguration, especially in multiplatform and multi-module environments. ## Getting started -With the `dokka-cli-%dokkaVersion%.jar` file saved on your computer, run it with the `-help` option to see all available arguments and their description: +The CLI runner is published to Maven Central as a separate runnable artifact. + +You can find it on [mvnrepository](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-cli/%dokkaVersion%) or by browsing +[maven central repository directories](https://repo1.maven.org/maven2/org/jetbrains/dokka/dokka-cli/%dokkaVersion%) directly. + +With the `dokka-cli-%dokkaVersion%.jar` file saved on your computer, run it with the `-help` option to see all +available configuration options and their description: ```Bash java -jar dokka-cli-%dokkaVersion%.jar -help ``` -It also works for some nested arguments, such as `-sourceSet`: +It also works for some nested options, such as `-sourceSet`: ```Bash java -jar dokka-cli-%dokkaVersion%.jar -sourceSet -help @@ -47,11 +49,12 @@ Below are the additional dependencies that you need for [HTML](html.md) output f | `org.freemarker` | `freemarker` | 2.3.31 | [mvnrepository](https://mvnrepository.com/artifact/org.freemarker/freemarker/2.3.31) | -### Running with command line arguments +### Running with command line options -You can pass command line arguments to configure the CLI runner. +You can pass command line options to configure the CLI runner. + +At the very least you need to provide the following options: -At the very least you need to provide the following arguments: * `-pluginsClasspath` - a list of absolute/relative paths to downloaded dependencies, separated by semi-colons `;` * `-sourceSet` - an absolute path to code sources to generate documentation for * `-outputDir` - an absolute/relative path of the documentation output directory @@ -70,18 +73,19 @@ java -jar dokka-cli-%dokkaVersion%.jar \ Executing the given example generates documentation in [HTML](html.md) output format. -See [Command line arguments](#command-line-arguments) for more configuration details. +See [Command line options](#command-line-options) for more configuration details. ### Running with JSON configuration It's possible to configure the CLI runner with JSON. In this case, you need to provide an -absolute/relative path to the JSON configuration file. All other configuration options are parsed from it. +absolute/relative path to the JSON configuration file as the first and only argument. +All other configuration options are parsed from it. ```Bash java -jar dokka-cli-%dokkaVersion%.jar dokka-configuration.json ``` -At the very least, you need the following configuration: +At the very least, you need the following JSON configuration file: ```json { "outputDir": "./dokka/html", @@ -118,14 +122,14 @@ See [JSON configuration options](#json-configuration) for more details. By default, the `dokka-base` artifact contains the [HTML](html.md) output format only. -All other output formats come as part of [Dokka plugins](plugins_introduction.md). In order to use them, you have to put them -in the plugins classpath. +All other output formats come as [Dokka plugins](dokka_plugins.md). In order to use them, you have to put them +on the plugins classpath. For example, if you want to generate documentation in the experimental [GFM](markdown.md#gfm) output format, you need to download and pass [gfm-plugin's JAR](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin/%dokkaVersion%) into the `pluginsClasspath` configuration option. -Via command line arguments: +Via command line options: ```Shell java -jar dokka-cli-%dokkaVersion%.jar \ @@ -147,51 +151,50 @@ Via JSON configuration: } ``` -With the GFM plugin in the `pluginsClasspath`, the CLI runner generates documentation in GFM output format. -No further action is needed. +With the GFM plugin passed to `pluginsClasspath`, the CLI runner generates documentation in the GFM output format. For more information, see [Markdown](markdown.md) and [Javadoc](javadoc.md#generating-javadoc-documentation). -## Command line arguments +## Command line options -To see a list of all possible command line arguments for the nested `-sourceSet` configuration, run: +To see the list of all possible command line options and their detailed description, run: ```Bash java -jar dokka-cli-%dokkaVersion%.jar -help ``` -Summary: +Short summary: - `-moduleName` -> Name of the project/module. - `-moduleVersion` -> Documented version. - `-outputDir` -> Output directory path, `./dokka` by default. -- `-sourceSet` -> Configuration for a Dokka source set. Contains nested configuration. +- `-sourceSet` -> Configuration for a Dokka source set. Contains nested configuration options. - `-pluginsConfiguration` -> Configuration for Dokka plugins. - `-pluginsClasspath` -> List of jars with Dokka plugins and their dependencies. Accepts multiple paths separated by semicolons. - `-offlineMode` -> Whether to resolve remote files/links over network. - `-failOnWarning` -> Whether to fail documentation generation if Dokka has emitted a warning or an error. -- `-delayTemplateSubstitution` -> Delay substitution of some elements. Used in incremental builds of - multimodule projects. -- `-noSuppressObviousFunctions` -> Whether to suppress obvious functions such as inherited from `kotlin.Any` +- `-delayTemplateSubstitution` -> Whether to delay substitution of some elements. Used in incremental builds of + multi-module projects. +- `-noSuppressObviousFunctions` -> Whether to suppress obvious functions such as those inherited from `kotlin.Any` and `java.lang.Object`. - `-includes` -> Markdown files that contain module and package documentation. Accepts multiple values separated by semicolons. - `-suppressInheritedMembers` -> Whether to suppress inherited members that aren't explicitly overridden in a given class. -- `-globalPackageOptions` -> Global list of package configurations in format +- `-globalPackageOptions` -> Global list of package configuration options in format `"matchingRegex,-deprecated,-privateApi,+warnUndocumented,+suppress;+visibility:PUBLIC;..."`. Accepts multiple values separated by semicolons. - `-globalLinks` -> Global external documentation links in format `{url}^{packageListUrl}`. Accepts multiple values separated by `^^`. - `-globalSrcLink` -> Global mapping between a source directory and a Web service for browsing the code. Accepts multiple paths separated by semicolons. -- `-helpSourceSet` -> Prints help for nested `-sourceSet` configuration. +- `-helpSourceSet` -> Prints help for the nested `-sourceSet` configuration. - `-loggingLevel` -> Logging level, possible values: `DEBUG, PROGRESS, INFO, WARN, ERROR`. - `-help, -h` -> Usage info. -#### Source set arguments +#### Source set options -You can also see short descriptions for nested `-sourceSet` configuration: +To see the list of command line options for the nested `-sourceSet` configuration, run: ```Bash java -jar dokka-cli-%dokkaVersion%.jar -sourceSet -help @@ -203,24 +206,23 @@ Summary: - `-displayName` -> Display name of the source set, used both internally and externally. - `-classpath` -> Classpath for analysis and interactive samples. Accepts multiple paths separated by semicolons. - `-src` -> Source code roots to be analyzed and documented. Accepts multiple paths separated by semicolons. -- `-dependentSourceSets` -> Names of dependent source sets in format `moduleName/sourceSetName`. +- `-dependentSourceSets` -> Names of the dependent source sets in format `moduleName/sourceSetName`. Accepts multiple paths separated by semicolons. - `-samples` -> List of directories or files that contain sample functions. Accepts multiple paths separated by semicolons. - `-includes` -> Markdown files that contain module and package documentation. Accepts multiple paths separated by semicolons. -- `-includeNonPublic` -> Deprecated, use `documentedVisibilities`. - Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL`, `PACKAGE`. - `-documentedVisibilities` -> Visibilities to be documented. Accepts multiple values separated by semicolons. + Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL`, `PACKAGE`. - `-reportUndocumented` -> Whether to report undocumented declarations. - `-noSkipEmptyPackages` -> Whether to create pages for empty packages. - `-skipDeprecated` -> Whether to skip deprecated declarations. - `-jdkVersion` -> Version of JDK to use for linking to JDK Javadocs. - `-languageVersion` -> Language version used for setting up analysis and samples. - `-apiVersion` -> Kotlin API version used for setting up analysis and samples. -- `-noStdlibLink` -> Whether to generate links to Standard library. +- `-noStdlibLink` -> Whether to generate links to the Kotlin standard library. - `-noJdkLink` -> Whether to generate links to JDK Javadocs. - `-suppressedFiles` -> Paths to files to be suppressed. Accepts multiple paths separated by semicolons. - `-analysisPlatform` -> Platform used for setting up analysis. -- `-perPackageOptions` -> List of package source set configuration in format +- `-perPackageOptions` -> List of package source set configurations in format `matchingRegexp,-deprecated,-privateApi,+warnUndocumented,+suppress;...`. Accepts multiple values separated by semicolons. - `-externalDocumentationLinks` -> External documentation links in format `{url}^{packageListUrl}`. Accepts multiple values separated by `^^`. @@ -272,11 +274,11 @@ with [all configuration options](#complete-configuration) applied. -

The display name used to refer to the module. Used in the table of contents, navigation, logging, etc.

+

The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.

Default: root.

 -

Module version.

+

The module version.

Default: empty.

 @@ -285,7 +287,7 @@ with [all configuration options](#complete-configuration) applied.

- Whether to fail documentation generation if Dokka emits a warning or an error. + Whether to fail documentation generation if Dokka has emitted a warning or an error. The process waits until all errors and warnings have been emitted first.

This setting works well with reportUndocumented

@@ -311,8 +313,7 @@ with [all configuration options](#complete-configuration) applied.

Whether to suppress inherited members that aren't explicitly overridden in a given class.

- Note: this can suppress functions such as equals / hashCode / -toString, + Note: this can suppress functions such as equals / hashCode / toString, but cannot suppress synthetic functions such as dataClass.componentN and dataClass.copy. Use suppressObviousFunctions for that. @@ -320,19 +321,19 @@ with [all configuration options](#complete-configuration) applied.

Default: false.

 -

Whether to resolve remote files/links over network.

+

Whether to resolve remote files/links over your network.

- This includes package-lists used for generating external documentation links. - For example, to make classes from standard library clickable. + This includes package-lists used for generating external documentation links. + For example, to make classes from the standard library clickable.

Setting this to true can significantly speed up build times in certain cases, but can also worsen documentation quality and user experience. For example, by - not resolving some dependency's class/member links. + not resolving class/member links from your dependencies, including the standard library.

Note: you can cache fetched files locally and provide them to - Dokka as local paths. See externalDocumentationLinks. + Dokka as local paths. See externalDocumentationLinks section.

Default: false.

 @@ -341,8 +342,7 @@ with [all configuration options](#complete-configuration) applied. A list of Markdown files that contain module and package documentation.

-

The contents of specified files are parsed and embedded into documentation as module and package -descriptions.

+

The contents of specified files are parsed and embedded into documentation as module and package descriptions.

This can be configured on per-package basis.

 @@ -353,7 +353,7 @@ descriptions.

For a list of possible options, see source set configuration.

 -

The global configuration of source links that are applied for all source sets.

+

The global configuration of source links that is applied for all source sets.

For a list of possible options, see source link configuration.

 @@ -431,7 +431,7 @@ How to configure Kotlin -

The display name used to refer to the source set.

+

The display name used to refer to this source set.

The name is used both externally (for example, the source set name is visible to documentation readers) and internally (for example, for logging messages of reportUndocumented). @@ -463,9 +463,10 @@ How to configure Kotlin

Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs - after they have been filtered by documentedVisibilities. + after they have been filtered by documentedVisibilities and other filters.

-

This setting works well with failOnWarning. It can be overridden for a specific package

+

This setting works well with failOnWarning.

+

This can be configured on per-package basis.

Default: false.

 @@ -481,14 +482,14 @@ How to configure Kotlin

Whether to document declarations annotated with @Deprecated.

-

It can be overridden at package level.

+

This can be configured on per-package basis.

Default: false.

The JDK version to use when generating external documentation links for Java types.

- For example, if you use java.util.UUID from JDK in some public declaration signature, - and this property is set to 8, Dokka generates an external documentation link + For example, if you use java.util.UUID in some public declaration signature, + and this option is set to 8, Dokka generates an external documentation link to JDK 8 Javadocs for it.

@@ -508,16 +509,16 @@ How to configure Kotlin

- Whether to generate external documentation links that lead to API reference - documentation for Kotlin's standard library when declarations from it are used. + Whether to generate external documentation links that lead to the API reference + documentation of Kotlin's standard library.

-

Links are generated when `noStdLibLink` is set to false.

+

Note: links are generated when noStdLibLink is set to false.

Default: false.

 -

Whether to generate external documentation links to JDK's Javadocs when declarations from it are used.

-

Links are generated when `noJdkLink` is set to false.

-

The version of JDK Javadocs is determined by jdkVersion property.

+

Whether to generate external documentation links to JDK's Javadocs.

+

The version of JDK Javadocs is determined by the jdkVersion option.

+

Note: links are generated when noJdkLink is set to false.

Default: false.

 @@ -532,7 +533,6 @@ How to configure Kotlin Platform to be used for setting up code analysis and @sample environment.

-

The default value is deduced from information provided by the Kotlin Gradle plugin.

Possible values: @@ -546,19 +546,17 @@ How to configure Kotlin

The source code roots to be analyzed and documented. - It accepts directories and individual .kt / .java files. + Acceptable inputs are directories and individual .kt / .java files.

-

- The classpath for analysis and interactive samples. If you use a declaration from a dependency, - it should be present on the classpath to be resolved. -

-

Property accepts both .jar and .klib files.

+

The classpath for analysis and interactive samples.

+

This is useful if some types that come from dependencies are not resolved/picked up automatically.

+

This option accepts both .jar and .klib files.

- A list of directories or files that contain sample functions which are referenced via + A list of directories or files that contain sample functions which are referenced via the @sample KDoc tag.

@@ -566,7 +564,7 @@ How to configure Kotlin

The files to be suppressed when generating documentation.

-

A set of parameters for source links that are applied only for this source set.

+

A set of parameters for source links that is applied only for this source set.

For a list of possible options, see source link configuration.

 @@ -574,22 +572,24 @@ How to configure Kotlin

For a list of possible options, see per-package configuration.

 -

A set of parameters for external documentation links that are applied only for this source set.

+

A set of parameters for external documentation links that is applied only for this source set.

For a list of possible options, see external documentation configuration.

 ### Source link configuration -The `sourceLinks` configuration block is where you can add a `source` link to each signature -that leads to a `remoteUrl` with a specific line number. (The line number is configurable by setting `remoteLineSuffix`). +The `sourceLinks` configuration block allows you to add a `source` link to each signature +that leads to the `remoteUrl` with a specific line number. (The line number is configurable by setting `remoteLineSuffix`). + This helps readers to find the source code for each declaration. For an example, see the documentation for the [`count()`](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/count.html) function in `kotlinx.coroutines`. -You can configure source sets together at the same time, or [individually](#source-set-configuration): +You can configure source links for all source sets together at the same time, or +[individually](#source-set-configuration): ```json { @@ -605,7 +605,7 @@ You can configure source sets together at the same time, or [individually](#sour -

Path to the local source directory.

+

The path to the local source directory.

@@ -616,12 +616,12 @@ You can configure source sets together at the same time, or [individually](#sour

- The suffix used to append source code line number to the URL. This helps readers navigate + The suffix used to append the source code line number to the URL. This helps readers navigate not only to the file, but to the specific line number of the declaration.

The number itself is appended to the specified suffix. For example, - if this property is set to #L and the line number is 10, the resulting URL suffix + if this option is set to #L and the line number is 10, the resulting URL suffix is #L10.

@@ -638,9 +638,10 @@ You can configure source sets together at the same time, or [individually](#sour ### Per-package configuration -The `perPackageOptions` configuration block allows you to set some options for specific packages matched by `matchingRegex`. +The `perPackageOptions` configuration block allows setting some options for specific packages matched by `matchingRegex`. -You can configure source sets together at the same time, or [individually](#source-set-configuration): +You can add package configurations for all source sets together at the same time, or +[individually](#source-set-configuration): ```json { @@ -671,8 +672,8 @@ You can configure source sets together at the same time, or [individually](#sour

- Whether to emit warnings about visible undocumented declarations, that is declarations from - this package and without KDocs, after they have been filtered by documentedVisibilities. + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by documentedVisibilities and other filters.

This setting works well with failOnWarning.

This can be configured on source set level.

@@ -681,8 +682,8 @@ You can configure source sets together at the same time, or [individually](#sour

The set of visibility modifiers that should be documented.

- This can be used if you want to document protected/internal/private declarations within a - specific package, as well as if you want to exclude public declarations and only document internal API. + This can be used if you want to document protected/internal/private declarations within this package, + as well as if you want to exclude public declarations and only document internal API.

Can be configured on source set level.

Default: PUBLIC.

@@ -691,15 +692,17 @@ You can configure source sets together at the same time, or [individually](#sour ### External documentation configuration -The `externalDocumentationLinks` configuration block allows you to add links that lead to the externally hosted documentation of your dependencies. +The `externalDocumentationLink` block allows the creation of links that lead to the externally hosted documentation of +your dependencies. For example, if you are using types from `kotlinx.serialization`, by default they are unclickable in your -documentation, as if they are unresolved. However, since the API reference for `kotlinx.serialization` is also built by Dokka and is -[published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/), you can configure external -documentation links for it. Thus allowing Dokka to generate links for types, making them clickable -and resolve successfully. +documentation, as if they are unresolved. However, since the API reference documentation for `kotlinx.serialization` +is built by Dokka and is [published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/), you can +configure external documentation links for it. Thus allowing Dokka to generate links for types from the library, making +them resolve successfully and clickable. -You can configure source sets together all at once, or [individually](#source-set-configuration): +You can configure external documentation links for all source sets together at the same time, or +[individually](#source-set-configuration): ```json { @@ -714,27 +717,32 @@ You can configure source sets together all at once, or [individually](#source-se -

The root URL of documentation to link with. It **must** contain a trailing slash.

+

The root URL of documentation to link to. It must contain a trailing slash.

- Dokka does its best to automatically find package-list for the given URL + Dokka does its best to automatically find package-list for the given URL, and link declarations together.

If automatic resolution fails or if you want to use locally cached files instead, - consider providing the packageListUrl. + consider setting the packageListUrl option.

The exact location of a package-list. This is an alternative to relying on Dokka - automatically resolving it. This can also be a locally cached file to avoid network calls. + automatically resolving it. +

+

+ Package lists contain information about the documentation and the project itself, + such as module and package names.

+

This can also be a locally cached file to avoid network calls.

 ### Complete configuration -Below you can see all the possible configuration options applied at the same time. +Below you can see all possible configuration options applied at the same time. ```json { diff --git a/docs/topics/runners/gradle.md b/docs/topics/runners/gradle.md index 9f05e58f1c..37fcde4e7e 100644 --- a/docs/topics/runners/gradle.md +++ b/docs/topics/runners/gradle.md @@ -1,17 +1,18 @@ -[//]: # (title: Gradle plugin) +[//]: # (title: Gradle) -To generate documentation for a Gradle-based project, you can use the [Dokka Gradle plugin](#applying-the-plugin). +To generate documentation for a Gradle-based project, you can use the +[Dokka Gradle plugin](https://plugins.gradle.org/plugin/org.jetbrains.dokka). It comes with basic autoconfiguration (including multi-project and multiplatform builds), has convenient [Gradle tasks](#generating-documentation) for generating documentation, and provides a great deal of -[configuration options](#configuration) to customize output. +[configuration options](#configuration) to customize the output. You can play around with Dokka and see how it can be configured for various projects by visiting our [Gradle example projects](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle). -## Applying the plugin +## Applying Dokka -The recommended way of applying the plugin is via +The recommended way of applying the Dokka Gradle plugin is with the [plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block): @@ -35,8 +36,8 @@ plugins { -When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply the Dokka plugin within subprojects as well. -You can use `allprojects {}` and `subprojects {}` Gradle configurations to achieve that: +When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply the Dokka Gradle plugin +within subprojects as well. You can use `allprojects {}` or `subprojects {}` Gradle configurations to achieve that: @@ -60,9 +61,8 @@ subprojects { > Under the hood, Dokka uses the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle.html) to perform -> autoconfiguration -> of [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) for documentation -> to be generated. Make sure to apply Kotlin Gradle Plugin or +> autoconfiguration of [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) for +> which documentation is to be generated. Make sure to apply the Kotlin Gradle Plugin or > [configure source sets](#source-set-configuration) manually. > {type="note"} @@ -91,13 +91,13 @@ subprojects { > {type="note"} -If you cannot use the plugin DSL for some reason, you can use +If you cannot use the plugins DSL for some reason, you can use [the legacy method](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application) of applying plugins. ## Generating documentation -Dokka's Gradle plugin comes with [HTML](html.md), [Markdown](markdown.md) and [Javadoc](javadoc.md) output formats built in. +Dokka's Gradle runner comes with [HTML](html.md), [Markdown](markdown.md) and [Javadoc](javadoc.md) output formats built in. It adds a number of tasks for generating documentation, both for [single](#single-project-builds) and [multi-project](#multi-project-builds) builds. @@ -119,17 +119,18 @@ Use the following tasks to build documentation for simple, single project applic | `dokkaJavadoc` | Generates documentation in [Javadoc](javadoc.md) format. | | `dokkaJekyll` | Generates documentation in [Jekyll compatible Markdown](markdown.md#jekyll) format. | -By default, generated documentation is stored in the `build/dokka/{format}` directory of your project. -The output location, among other things, can be [configured](#configuration) separately. +By default, generated documentation is located in the `build/dokka/{format}` directory of your project. +The output location, among other things, can be [configured](#configuration). ### Multi-project builds For documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html), make sure -that you apply the Dokka plugin within subprojects that you want to generate documentation for, as well as in their parent project. +that you [apply the Dokka Gradle plugin](#applying-dokka) within subprojects that you want to generate documentation +for, as well as in their parent project. #### MultiModule tasks -`MultiModule` tasks generate documentation for each subproject individually via [partial](#partial-tasks) tasks, +`MultiModule` tasks generate documentation for each subproject individually via [Partial](#partial-tasks) tasks, collect and process all outputs, and produce complete documentation with a common table of contents and resolved cross-project references. @@ -148,14 +149,14 @@ Dokka creates the following tasks for **parent** projects automatically: | `dokkaGfmMultiModule` | Generates multi-module documentation in [GitHub Flavored Markdown](markdown.md#gfm) output format. | | `dokkaJekyllMultiModule` | Generates multi-module documentation in [Jekyll compatible Markdown](markdown.md#jekyll) output format. | -> The [Javadoc](javadoc.md) output format does not have a MultiModule task, but a [Collector](#collector-tasks) task can +> The [Javadoc](javadoc.md) output format does not have a `MultiModule` task, but a [Collector](#collector-tasks) task can > be used instead. > {type="note"} By default, you can find ready-to-use documentation under `{parentProject}/build/dokka/{format}MultiModule` directory. -#### MultiModule task example +#### MultiModule results Given a project with the following structure: @@ -173,29 +174,15 @@ These pages are generated after running `dokkaHtmlMultiModule`: ![Screenshot for output of dokkaHtmlMultiModule task](dokkaHtmlMultiModule-example.png){width=600} -See our [multi-module project example](https://github. -com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) +See our [multi-module project example](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) for more details. -#### Partial tasks - -Each subproject has _partial_ tasks created for it: `dokkaHtmlPartial`,`dokkaGfmPartial`, -and `dokkaJekyllPartial`. - -These tasks are not intended to be used independently and exist only to be called by the parent's -[MultiModule](#multimodule-tasks) task. - -Output generated by partial tasks contains non-displayable formatting along with unresolved templates and references. - -> If you want to generate documentation for a single subproject only, use -> [single project tasks](#single-project-builds). For example, `:subproject:dokkaHtml`. - #### Collector tasks -Similar to MultiModule tasks, _Collector_ tasks are created for each parent project: `dokkaHtmlCollector`, +Similar to `MultiModule` tasks, `Collector` tasks are created for each parent project: `dokkaHtmlCollector`, `dokkaGfmCollector`, `dokkaJavadocCollector` and `dokkaJekyllCollector`. -A Collector task executes the corresponding [single project task](#single-project-builds) for each subproject (for +A `Collector` task executes the corresponding [single project task](#single-project-builds) for each subproject (for example, `dokkaHtml`), and merges all outputs into a single virtual project. @@ -224,16 +211,37 @@ These pages are generated after running `dokkaHtmlCollector`: ![Screenshot for output of dokkaHtmlCollector task](dokkaHtmlCollector-example.png){width=800} -See our [multi-module project example](https://github. -com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) +See our [multi-module project example](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example) for more details. +#### Partial tasks + +Each subproject has `Partial` tasks created for it: `dokkaHtmlPartial`,`dokkaGfmPartial`, +and `dokkaJekyllPartial`. + +These tasks are not intended to be used independently and exist only to be called by the parent's +[MultiModule](#multimodule-tasks) task. + +Output generated by `Partial` tasks contains unresolved HTML templates and references, so it cannot be used +on its own without post-processing done by the `MultiModule` task. + +However, you can [configure](#configuration) `Partial` tasks to customize Dokka on a per-project basis. +For example, your subprojects can have different configurations of documented visibilities, where one of +the subprojects allows documenting `protected` declarations, while others do not. + +> If you want to generate documentation for a single subproject only, use +> [single project tasks](#single-project-builds). For example, `:subprojectName:dokkaHtml`. + ## Building javadoc.jar -In order to publish your library to a repository, you may need to provide a `javadoc.jar` file that contains API -reference documentation. +If you want to publish your library to a repository, you may need to provide a `javadoc.jar` file that contains +API reference documentation of your library. + +For example, if you want to publish to [Maven Central](https://central.sonatype.org/), you +[must](https://central.sonatype.org/publish/requirements/) supply a `javadoc.jar` alongside your project. However, +not all repositories have that rule. -Dokka's Gradle plugin does not provide any way to do this out of the box, but it can be achieved with custom Gradle +Dokka's Gradle runner does not provide any way to do this out of the box, but it can be achieved with custom Gradle tasks. One for generating documentation in [HTML](html.md) format and another one for [Javadoc](javadoc.md) format: @@ -275,7 +283,7 @@ tasks.register('dokkaJavadocJar', Jar.class) { > If you publish your library to Maven Central, you can use services like [javadoc.io](https://javadoc.io/) to > host your library's API documentation for free and without any setup. It takes documentation pages straight -> from the artifact. It works with both HTML and Javadoc formats as demonstrated in +> from the `javadoc.jar`. It works well with the HTML format as demonstrated in > [this example](https://javadoc.io/doc/com.trib3/server/latest/index.html). > {type="tip"} @@ -287,8 +295,6 @@ You can configure tasks and output formats individually: -Applying the Dokka plugin via the [plugins DSL](#applying-the-plugin) block: - ```kotlin tasks.dokkaHtml { outputDirectory.set(buildDir.resolve("documentation/html")) @@ -298,6 +304,7 @@ tasks.dokkaGfm { outputDirectory.set(buildDir.resolve("documentation/markdown")) } +// only within a subproject: tasks.dokkaHtmlPartial { outputDirectory.set(buildDir.resolve("docs/partial")) } @@ -316,6 +323,7 @@ dokkaGfm { outputDirectory.set(file("build/documentation/markdown")) } +// only within a subproject: dokkaHtmlPartial { outputDirectory.set(file("build/docs/partial")) } @@ -335,8 +343,8 @@ import org.jetbrains.dokka.gradle.DokkaTask import org.jetbrains.dokka.gradle.DokkaTaskPartial import org.jetbrains.dokka.DokkaConfiguration.Visibility -// configure all dokka tasks, including multimodule, -// partial and collector ones +// Configure all single-project Dokka tasks at the same time, +// such as dokkaHtml, dokkaJavadoc and dokkaGfm. tasks.withType().configureEach { dokkaSourceSets.configureEach { documentedVisibilities.set( @@ -353,11 +361,16 @@ tasks.withType().configureEach { } } -// Configure partial tasks of all output formats. +// Configure all Partial tasks found in multi-project builds, +// such as dokkaHtmlPartial, dokkaJavadocPartial and dokkaGfmPartial. // These can have subproject-specific settings. -tasks.withType(DokkaTaskPartial::class).configureEach { - dokkaSourceSets.configureEach { - includes.from("README.md") +subprojects { + apply(plugin = "org.jetbrains.dokka") + + tasks.withType().configureEach { + dokkaSourceSets.configureEach { + includes.from("README.md") + } } } ``` @@ -369,8 +382,8 @@ tasks.withType(DokkaTaskPartial::class).configureEach { import org.jetbrains.dokka.gradle.DokkaTask import org.jetbrains.dokka.gradle.DokkaTaskPartial -// Configure all Dokka tasks, including multimodule, -// partial and collector tasks +// Configure all single-project Dokka tasks at the same time, +// such as dokkaHtml, dokkaJavadoc and dokkaGfm. tasks.withType(DokkaTask.class) { dokkaSourceSets.configureEach { documentedVisibilities.set([ @@ -385,11 +398,15 @@ tasks.withType(DokkaTask.class) { } } -// Configure partial tasks of all output formats. +// Configure all Partial tasks found in multi-project builds. // These can have subproject-specific settings. -tasks.withType(DokkaTaskPartial.class) { - dokkaSourceSets.configureEach { - includes.from("README.md") +subprojects { + apply plugin: 'org.jetbrains.dokka' + + tasks.withType(DokkaTaskPartial.class) { + dokkaSourceSets.configureEach { + includes.from("README.md") + } } } ``` @@ -456,20 +473,20 @@ tasks.withType(DokkaTask.class) {

The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.

-

If set for a single-project build or a MultiModule task, it is used as the project name.

-

The default is the Gradle project name.

+

If set for a single-project build or a MultiModule task, it is used as the project name.

+

Default: Gradle project name.

- The module version. If set for a single-project build or a MultiModule task, it is used as the project version - by the versioning plugin. + The module version. If set for a single-project build or a MultiModule task, it is used as the + project version.

Default: Gradle project version.

 -

The directory where documentation is generated, regardless of format. It can be set on a per-task basis.

+

The directory to where documentation is generated, regardless of format. It can be set on a per-task basis.

- The default is project/buildDir/format, where format is the task name with + The default is {project}/{buildDir}/{format}, where {format} is the task name with the "dokka" prefix removed. For the dokkaHtmlMultiModule task, it is project/buildDir/htmlMultiModule.

@@ -479,7 +496,7 @@ tasks.withType(DokkaTask.class) { Whether to fail documentation generation if Dokka has emitted a warning or an error. The process waits until all errors and warnings have been emitted first.

-

This setting works well with reportUndocumented

+

This setting works well with reportUndocumented.

Default: false.

 @@ -513,12 +530,12 @@ tasks.withType(DokkaTask.class) {

Whether to resolve remote files/links over your network.

This includes package-lists used for generating external documentation links. - For example, to make classes from standard library clickable. + For example, to make classes from the standard library clickable.

Setting this to true can significantly speed up build times in certain cases, but can also worsen documentation quality and user experience. For example, by - not resolving some dependency's class/member links. + not resolving class/member links from your dependencies, including the standard library.

Note: you can cache fetched files locally and provide them to @@ -530,7 +547,8 @@ tasks.withType(DokkaTask.class) { ### Source set configuration -Here is an example of how to configure Kotlin [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets). +Dokka allows configuring some options for +[Kotlin source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets): @@ -545,6 +563,12 @@ tasks.withType().configureEach { // .. // general configuration section // .. + + // configuration exclusive to the 'linux' source set + named("linux") { + dependsOn("native") + sourceRoots.from(file("linux/src")) + } dokkaSourceSets.configureEach { suppress.set(false) @@ -593,6 +617,12 @@ tasks.withType(DokkaTask.class) { // general configuration section // .. + // configuration exclusive to the 'linux' source set + named("linux") { + dependsOn("native") + sourceRoots.from(file("linux/src")) + } + dokkaSourceSets.configureEach { suppress.set(false) displayName.set(name) @@ -635,7 +665,7 @@ tasks.withType(DokkaTask.class) {

Default: false.

 -

The display name used to refer to the source set.

+

The display name used to refer to this source set.

The name is used both externally (for example, as source set name visible to documentation readers) and internally (for example, for logging messages of reportUndocumented). @@ -648,15 +678,16 @@ tasks.withType(DokkaTask.class) { This can be used if you want to document protected/internal/private declarations, as well as if you want to exclude public declarations and only document internal API.

-

Can be configured on per-package basis.

+

This can be configured on per-package basis.

Default: DokkaConfiguration.Visibility.PUBLIC.

Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs - after they have been filtered by documentedVisibilities. + after they have been filtered by documentedVisibilities and other filters.

-

This setting works well with failOnWarning. It can be overridden for a specific package.

+

This setting works well with failOnWarning.

+

This can be configured on per-package basis.

Default: false.

 @@ -672,13 +703,15 @@ tasks.withType(DokkaTask.class) {

Whether to document declarations annotated with @Deprecated.

-

It can be overridden at package level.

+

This can be configured on per-package basis.

Default: false.

Whether to document/analyze generated files.

Generated files are expected to be present under the {project}/{buildDir}/generated directory. +

+

If set to true, it effectively adds all files from that directory to the suppressedFiles option, so you can configure it manually.

@@ -687,8 +720,8 @@ tasks.withType(DokkaTask.class) {

The JDK version to use when generating external documentation links for Java types.

- For example, if you use java.util.UUID from the JDK in some public declaration signature, - and this property is set to 8, Dokka generates an external documentation link + For example, if you use java.util.UUID in some public declaration signature, + and this option is set to 8, Dokka generates an external documentation link to JDK 8 Javadocs for it.

Default: JDK 8.

@@ -711,25 +744,22 @@ tasks.withType(DokkaTask.class) {

- Whether to generate external documentation links that lead to API reference - documentation for Kotlin's standard library when declarations from it are used. + Whether to generate external documentation links that lead to the API reference + documentation of Kotlin's standard library.

-

Links are generated when `noStdLibLink` is set to false.

+

Note: links are generated when noStdLibLink is set to false.

Default: false.

 -

Whether to generate external documentation links to JDK's Javadocs when declarations from it are used.

-

The version of JDK Javadocs is determined by the jdkVersion property.

-

Links are generated when `noJdkLink` is set to false.

+

Whether to generate external documentation links to JDK's Javadocs.

+

The version of JDK Javadocs is determined by the jdkVersion option.

+

Note: links are generated when noJdkLink is set to false.

Default: false.

 -

- Whether to generate external documentation links for Android SDK API reference - when declarations from it are used. -

+

Whether to generate external documentation links to the Android SDK API reference

This is only relevant in Android projects, ignored otherwise.

-

Links are generated when `noAndroidSdkLink` is set to false.

+

Note: links are generated when noAndroidSdkLink is set to false.

Default: false.

 @@ -740,7 +770,7 @@ tasks.withType(DokkaTask.class) {

The contents of the specified files are parsed and embedded into documentation as module and package descriptions.

See Dokka gradle example - for an example of how to use it and what it looks like. + for an example of what it looks like and how to use it.

@@ -753,21 +783,19 @@ tasks.withType(DokkaTask.class) {

The source code roots to be analyzed and documented. - Acceptable formats are directories and individual .kt / .java files. + Acceptable inputs are directories and individual .kt / .java files.

By default, source roots are deduced from information provided by the Kotlin Gradle plugin.

The classpath for analysis and interactive samples.

-

- This iu Useful if some types that come from dependencies are not resolved/picked up automatically. - The property accepts both .jar and .klib files. -

+

This is useful if some types that come from dependencies are not resolved/picked up automatically.

+

This option accepts both .jar and .klib files.

By default, classpath is deduced from information provided by the Kotlin Gradle plugin.

- A list of directories or files that contain sample functions which are referenced via + A list of directories or files that contain sample functions which are referenced via the @sample KDoc tag.

@@ -775,8 +803,9 @@ tasks.withType(DokkaTask.class) { ### Source link configuration -The `sourceLinks` configuration block is where you can add a `source` link to each signature -that leads to a `remoteUrl` with a specific line number. (The line number is configurable by setting `remoteLineSuffix`). +The `sourceLinks` configuration block allows you to add a `source` link to each signature +that leads to the `remoteUrl` with a specific line number. (The line number is configurable by setting `remoteLineSuffix`). + This helps readers to find the source code for each declaration. For an example, see the documentation for the @@ -802,7 +831,7 @@ tasks.withType().configureEach { sourceLink { localDirectory.set(projectDir.resolve("src")) - remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src/main/kotlin")) + remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src")) remoteLineSuffix.set("#L") } } @@ -828,7 +857,7 @@ tasks.withType(DokkaTask.class) { sourceLink { localDirectory.set(file("src")) - remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src/main/kotlin")) + remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src")) remoteLineSuffix.set("#L") } } @@ -859,7 +888,7 @@ tasks.withType(DokkaTask.class) {

The number itself is appended to the specified suffix. For example, - if this property is set to #L and the line number is 10, the resulting URL suffix + if this option is set to #L and the line number is 10, the resulting URL suffix is #L10.

@@ -876,7 +905,7 @@ tasks.withType(DokkaTask.class) { ### Package options -Here is an example of a configuration block that allows setting some options for specific packages matched by `matchingRegex`. +The `perPackageOption` configuration block allows setting some options for specific packages matched by `matchingRegex`. @@ -940,7 +969,7 @@ tasks.withType(DokkaTask.class) {

The regular expression that is used to match the package.

-

Default: any string: .*.

+

Default: .*.

Whether this package should be skipped when generating documentation.

@@ -953,8 +982,8 @@ tasks.withType(DokkaTask.class) {

- Whether to emit warnings about visible undocumented declarations. That is declarations from - this package and without KDocs, after they have been filtered by documentedVisibilities. + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by documentedVisibilities and other filters.

This setting works well with failOnWarning.

This can be configured on source set level.

@@ -963,8 +992,8 @@ tasks.withType(DokkaTask.class) {

The set of visibility modifiers that should be documented.

- This can be used if you want to document protected/internal/private declarations within a - specific package, as well as if you want to exclude public declarations and only document internal API. + This can be used if you want to document protected/internal/private declarations within this package, + as well as if you want to exclude public declarations and only document internal API.

This can be configured on source set level.

Default: DokkaConfiguration.Visibility.PUBLIC.

@@ -973,13 +1002,16 @@ tasks.withType(DokkaTask.class) { ### External documentation links configuration -The externalDocumentationLink` block allows the creation of links that lead to the externally hosted documentation of your dependencies. +The `externalDocumentationLink` block allows the creation of links that lead to the externally hosted documentation of +your dependencies. For example, if you are using types from `kotlinx.serialization`, by default they are unclickable in your -documentation, as if they are unresolved. However, since the API reference for `kotlinx.serialization` is also built by Dokka and is -[published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/), you can configure external -documentation links for it. Thus allowing Dokka to generate links for types, making them clickable -and resolve successfully. +documentation, as if they are unresolved. However, since the API reference documentation for `kotlinx.serialization` +is built by Dokka and is [published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/), you can +configure external documentation links for it. Thus allowing Dokka to generate links for types from the library, making +them resolve successfully and clickable. + +By default, external documentation links for Kotlin standard library, JDK, Android SDK and AndroidX are configured. @@ -1040,21 +1072,26 @@ tasks.withType(DokkaTask.class) { -

The root URL of documentation to link with. It **must** contain a trailing slash.

+

The root URL of documentation to link to. It must contain a trailing slash.

Dokka does its best to automatically find package-list for the given URL, and link declarations together.

If automatic resolution fails or if you want to use locally cached files instead, - consider providing packageListUrl. + consider setting the packageListUrl option.

- Specifies the exact location of a package-list instead of relying on Dokka - automatically resolving it. It can also be a locally cached file to avoid network calls. + The exact location of a package-list. This is an alternative to relying on Dokka + automatically resolving it. +

+

+ Package lists contain information about the documentation and the project itself, + such as module and package names.

+

This can also be a locally cached file to avoid network calls.

 @@ -1081,8 +1118,9 @@ tasks.withType().configureEach { offlineMode.set(false) dokkaSourceSets { - named("customSourceSet") { - dependsOn("sourceSetDependency") + named("linux") { + dependsOn("native") + sourceRoots.from(file("linux/src")) } configureEach { suppress.set(false) @@ -1106,7 +1144,7 @@ tasks.withType().configureEach { sourceLink { localDirectory.set(projectDir.resolve("src")) - remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src/main/kotlin")) + remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src")) remoteLineSuffix.set("#L") } @@ -1156,8 +1194,9 @@ tasks.withType(DokkaTask.class) { offlineMode.set(false) dokkaSourceSets { - named("customSourceSet") { - dependsOn("sourceSetDependency") + named("linux") { + dependsOn("native") + sourceRoots.from(file("linux/src")) } configureEach { suppress.set(false) @@ -1181,7 +1220,7 @@ tasks.withType(DokkaTask.class) { sourceLink { localDirectory.set(file("src")) - remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src/main/kotlin")) + remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src")) remoteLineSuffix.set("#L") } diff --git a/docs/topics/runners/maven.md b/docs/topics/runners/maven.md index 7ba7dcea44..40bb9306f8 100644 --- a/docs/topics/runners/maven.md +++ b/docs/topics/runners/maven.md @@ -1,18 +1,18 @@ -[//]: # (title: Maven plugin) +[//]: # (title: Maven) -To generate documentation for Maven-based projects, you can use the [Dokka Maven plugin](#applying-the-plugin). +To generate documentation for a Maven-based project, you can use the [Dokka Maven plugin](#applying-dokka). -> Compared to the [Gradle plugin](gradle.md), the Maven plugin has only basic features and -> does not provide support for multimodule builds out of the box. +> Compared to the [Gradle runner](gradle.md), the Maven runner has only basic features and +> does not provide support for multi-module builds. > {type="note"} You can play around with Dokka and see how it can be configured for a Maven project by visiting our [Maven example](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/maven) project. -## Applying the plugin +## Applying Dokka -To apply the plugin, you need to add it to the plugins section of your POM file: +To apply Dokka, you need to add `dokka-maven-plugin` to the `plugins` section of your POM file: ```xml @@ -53,11 +53,11 @@ The following goals are provided by the plugin: ### Other output formats -By default, the Maven plugin builds documentation in [HTML](html.md) output format. +By default, the Maven runner builds documentation in [HTML](html.md) output format. -All other output formats come as part of [Dokka plugins](plugins_introduction.md). In order to use them, you have to apply +All other output formats come as [Dokka plugins](dokka_plugins.md). In order to use them, you have to apply TODO -For example, to use the experimental [GFM](markdown.md#gfm) format, you have to apply `org.jetbrains.dokka:gfm-plugin` in +For example, to use the experimental [GFM](markdown.md#gfm) format, you have to apply `org.jetbrains.dokka:gfm-plugin` in TODO ```xml @@ -78,14 +78,21 @@ For example, to use the experimental [GFM](markdown.md#gfm) format, you have to With this configuration, running the `dokka:dokka` goal produces documentation in GFM format. -To learn more about Dokka plugins, see [Dokka plugins](plugins_introduction.md). +To learn more about Dokka plugins, see [Dokka plugins](dokka_plugins.md). ## Building javadoc.jar -Unlike the [Gradle plugin](gradle.md#building-javadoc-jar), the Maven plugin comes with a ready-to-use `dokka:javadocJar` goal. -By default, it generates documentation in [Javadoc](javadoc.md) output format in the`target` folder. +If you want to publish your library to a repository, you may need to provide a `javadoc.jar` file that contains +API reference documentation of your library. -If you are not satisfied with the built-in goal or want to customize the output (for instance, you want to generate +For example, if you want to publish to [Maven Central](https://central.sonatype.org/), you +[must](https://central.sonatype.org/publish/requirements/) supply a `javadoc.jar` alongside your project. However, +not all repositories have that rule. + +Unlike the [Gradle runner](gradle.md#building-javadoc-jar), the Maven runner comes with a ready-to-use `dokka:javadocJar` +goal. By default, it generates documentation in [Javadoc](javadoc.md) output format in the`target` folder. + +If you are not satisfied with the built-in goal or want to customize the output (for example, you want to generate documentation in [HTML](html.md) format instead of Javadoc), similar behavior can be achieved by adding the Maven JAR plugin with the following configuration: @@ -116,12 +123,19 @@ Maven JAR plugin with the following configuration: ``` -The documentation and the `.jar` archive for it is then generated by running `dokka:dokka` and `jar:jar@dokka-jar` goals: +The documentation and the `.jar` archive for it are then generated by running `dokka:dokka` and `jar:jar@dokka-jar` goals: ```Bash mvn dokka:dokka jar:jar@dokka-jar ``` +> If you publish your library to Maven Central, you can use services like [javadoc.io](https://javadoc.io/) to +> host your library's API documentation for free and without any setup. It takes documentation pages straight +> from the `javadoc.jar`. It works well with the HTML format as demonstrated in +> [this example](https://javadoc.io/doc/com.trib3/server/latest/index.html). +> +{type="tip"} + ## Configuration Maven's plugin configuration block can be used to configure Dokka. @@ -141,7 +155,7 @@ Here is an example of a basic configuration that only changes the output locatio ## Configuration options -Dokka has many configuration options to tailor your experience. +Dokka has many configuration options to tailor your and your reader's experience. Below are some examples and detailed descriptions for each configuration section. You can also find an example with [all configuration options](#complete-configuration) applied. @@ -162,7 +176,7 @@ with [all configuration options](#complete-configuration) applied. false false - ${project.basedir}/src/main/kotlin + ${project.basedir}/src PUBLIC @@ -211,7 +225,7 @@ with [all configuration options](#complete-configuration) applied.

Default: {project.artifactId}.

 -

The directory where documentation is generated.

+

The directory to where documentation is generated, regardless of format.

Default: {project.basedir}/target/dokka.

 @@ -229,7 +243,7 @@ with [all configuration options](#complete-configuration) applied.
  • Inherited from kotlin.Any, Kotlin.Enum, java.lang.Object or - java.lang.Enum, such as equals, hashCode, toString`. + java.lang.Enum, such as equals, hashCode, toString.
  • Synthetic (generated by the compiler) and does not have any documentation, such as @@ -249,19 +263,19 @@ with [all configuration options](#complete-configuration) applied.

    Default: false.

    -

    Whether to resolve remote files/links over network.

    +

    Whether to resolve remote files/links over your network.

    - This includes package-lists used for generating external documentation links: - for instance, to make classes from standard library clickable. + This includes package-lists used for generating external documentation links. + For example, to make classes from the standard library clickable.

    Setting this to true can significantly speed up build times in certain cases, - but can also worsen documentation quality and user experience, for example by - not resolving some dependency's class/member links. + but can also worsen documentation quality and user experience. For example, by + not resolving class/member links from your dependencies, including the standard library.

    - When using offline mode, you can cache fetched files locally and provide them to - Dokka as local paths, see externalDocumentationLinks section. + Note: you can cache fetched files locally and provide them to + Dokka as local paths. See externalDocumentationLinks section.

    Default: false.

     @@ -283,8 +297,8 @@ with [all configuration options](#complete-configuration) applied.

    - Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs - after they have been filtered by documentedVisibilities. + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by documentedVisibilities and other filters.

    This setting works well with failOnWarning.

    This can be overridden at package level.

    @@ -296,10 +310,14 @@ with [all configuration options](#complete-configuration) applied.

    Default: false.

     -

    Whether to skip packages that contain no visible declarations after various filters have been applied.

    - For example, if skipDeprecated is set to true and your package contains only - deprecated declarations, it is considered empty.

    + Whether to skip packages that contain no visible declarations after + various filters have been applied. +

    +

    + For example, if skipDeprecated is set to true and your package contains only + deprecated declarations, it is considered to be empty. +

    Default: true.

     @@ -311,8 +329,8 @@ with [all configuration options](#complete-configuration) applied.

    The JDK version to use when generating external documentation links for Java types.

    - For example, if you use java.util.UUID from JDK in some public declaration signature, - and this property is set to 8, Dokka generates an external documentation link + For example, if you use java.util.UUID in some public declaration signature, + and this option is set to 8, Dokka generates an external documentation link to JDK 8 Javadocs for it.

    Default: JDK 8.

    @@ -335,16 +353,16 @@ with [all configuration options](#complete-configuration) applied.

    - Whether to generate external documentation links that lead to API reference - documentation for Kotlin's standard library when declarations from it are used. + Whether to generate external documentation links that lead to the API reference + documentation of Kotlin's standard library.

    -

    Links are generated when `noStdLibLink` is set to false.

    +

    Note: links are generated when noStdLibLink is set to false.

    Default: false.

     -

    Whether to generate external documentation links to JDK's Javadocs when declarations from it are used.

    -

    The version of JDK Javadocs is determined by jdkVersion property.

    -

    Links are generated when `noJdkLink` is set to false.

    +

    Whether to generate external documentation links to JDK's Javadocs.

    +

    The version of JDK Javadocs is determined by the jdkVersion option.

    +

    Note: links are generated when noJdkLink is set to false.

    Default: false

     @@ -358,7 +376,7 @@ with [all configuration options](#complete-configuration) applied.

    The classpath for analysis and interactive samples.

    This is useful if some types that come from dependencies are not resolved/picked up automatically. - The property accepts both .jar and .klib files. + This option accepts both .jar and .klib files.

    Default: {project.compileClasspathElements}.

     @@ -372,13 +390,14 @@ with [all configuration options](#complete-configuration) applied. ### Source link configuration -The `sourceLinks` configuration block is where you can add a `source` link to each signature -that leads to a `remoteUrl` with a specific line number. (The line number is configurable by setting `remoteLineSuffix`). +The `sourceLinks` configuration block allows you to add a `source` link to each signature +that leads to the `url` with a specific line number. (The line number is configurable by setting `lineSuffix`). + This helps readers to find the source code for each declaration. -For an example, see documentation for -[count](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/count.html) -function from `kotlinx.coroutines`. +For an example, see the documentation for the +[`count()`](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/count.html) +function in `kotlinx.coroutines`. ```xml @@ -388,8 +407,8 @@ function from `kotlinx.coroutines`. - ${project.basedir}/src/main/kotlin - https://github.com/kotlin/dokka/tree/master/src/main/kotlin + ${project.basedir}/src + https://github.com/kotlin/dokka/tree/master/src #L @@ -406,8 +425,9 @@ function from `kotlinx.coroutines`.

    - The URL of the source code hosting service that can be accessed by documentation readers, like GitHub, GitLab, - Bitbucket, etc. This URL is used to generate source code links of declarations. + The URL of the source code hosting service that can be accessed by documentation readers, + like GitHub, GitLab, Bitbucket, etc. This URL is used to generate + source code links of declarations.

    @@ -416,7 +436,7 @@ function from `kotlinx.coroutines`. to the file, but to the specific line number of the declaration.

    - The number itself is appended to the specified suffix. For example, if this property is set + The number itself is appended to the specified suffix. For example, if this option is set to #L and the line number is 10, the resulting URL suffix is #L10.

    @@ -432,13 +452,16 @@ function from `kotlinx.coroutines`. #### External documentation links configuration -The `externalDocumentationLinks` block allows the creation of links that lead to the externally hosted documentation of your dependencies. +The `externalDocumentationLink` block allows the creation of links that lead to the externally hosted documentation of +your dependencies. -For example, if you are using types from `kotlinx.serialization`, by default they are be unclickable in your -documentation, as if they are unresolved. However, since the API reference for `kotlinx.serialization` is also built by Dokka and is -[published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/), you can configure external -documentation links for it. Thus allowing Dokka to generate links for types, making them clickable -and resolve successfully. +For example, if you are using types from `kotlinx.serialization`, by default they are unclickable in your +documentation, as if they are unresolved. However, since the API reference documentation for `kotlinx.serialization` +is built by Dokka and is [published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/), you can +configure external documentation links for it. Thus allowing Dokka to generate links for types from the library, making +them resolve successfully and clickable. + +By default, external documentation links for Kotlin standard library and JDK are configured. ```xml @@ -458,27 +481,32 @@ and resolve successfully. -

    The root URL of documentation to link with. It **must** contain a trailing slash.

    +

    The root URL of documentation to link to. It must contain a trailing slash.

    - Dokka does its best to automatically find the package-list for the given URL + Dokka does its best to automatically find the package-list for the given URL, and link declarations together.

    If automatic resolution fails or if you want to use locally cached files instead, - consider providing the packageListUrl. + consider setting the packageListUrl option.

    The exact location of a package-list. This is an alternative to relying on Dokka - automatically resolving it. This can also be a locally cached file to avoid network calls. + automatically resolving it. +

    +

    + Package lists contain information about the documentation and the project itself, + such as module and package names.

    +

    This can also be a locally cached file to avoid network calls.

     ### Package options -The `packageOptions` configuration block allows you to set some options for specific packages matched by `matchingRegex`. +The `perPackageOptions` configuration block allows setting some options for specific packages matched by `matchingRegex`. ```xml @@ -508,17 +536,17 @@ The `packageOptions` configuration block allows you to set some options for spec

    The regular expression that is used to match the package.

    -

    Default: any string: .*.

    -     +

    Default: .*.

    +

    Whether this package should be skipped when generating documentation.

    Default: false.

     -

    A list of visibility modifiers that should be documented.

    +

    The set of visibility modifiers that should be documented.

    - This can be used if you want to document protected/internal/private declarations within a - specific package, as well as if you want to exclude public declarations and only document internal API. + This can be used if you want to document protected/internal/private declarations within this package, + as well as if you want to exclude public declarations and only document internal API.

    Default: PUBLIC.

     @@ -529,8 +557,8 @@ The `packageOptions` configuration block allows you to set some options for spec

    - Whether to emit warnings about visible undocumented declarations, that is declarations from - this package and without KDocs, after they have been filtered by documentedVisibilities. + Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs + after they have been filtered by documentedVisibilities and other filters.

    This setting works well with failOnWarning.

    Default: false.

    @@ -555,7 +583,7 @@ Below you can see all the possible configuration options applied at the same tim false false - ${project.basedir}/src/main/kotlin + ${project.basedir}/src PUBLIC @@ -586,8 +614,8 @@ Below you can see all the possible configuration options applied at the same tim - ${project.basedir}/src/main/kotlin - https://github.com/kotlin/dokka/tree/master/src/main/kotlin + ${project.basedir}/src + https://github.com/kotlin/dokka/tree/master/src #L diff --git a/examples/maven/pom.xml b/examples/maven/pom.xml index 40525fdbf6..74675d6d01 100644 --- a/examples/maven/pom.xml +++ b/examples/maven/pom.xml @@ -21,7 +21,7 @@ - ${project.basedir}/src/main/kotlin + ${project.basedir}/src diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt index 8e118767b2..4a0c133379 100644 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt +++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt @@ -18,7 +18,7 @@ import java.net.URL * ```kotlin * sourceLink { * localDirectory.set(projectDir.resolve("src")) - * remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src/main/kotlin")) + * remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src")) * remoteLineSuffix.set("#L") * } * ``` @@ -48,7 +48,7 @@ class GradleSourceLinkBuilder( * Example: * * ```kotlin - * java.net.URL("https://github.com/username/projectname/tree/master/src/main/kotlin")) + * java.net.URL("https://github.com/username/projectname/tree/master/src")) * ``` */ @Input diff --git a/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt b/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt index bd6d3baee5..621b38d85c 100644 --- a/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt +++ b/runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt @@ -12,8 +12,8 @@ import org.apache.maven.plugins.annotations.Parameter * ```xml * * - * ${project.basedir}/src/main/kotlin - * https://github.com/kotlin/dokka/tree/master/src/main/kotlin + * ${project.basedir}/src + * https://github.com/kotlin/dokka/tree/master/src * #L * * @@ -27,7 +27,7 @@ class SourceLinkMapItem { * Example: * * ```xml - * ${project.basedir}/src/main/kotlin + * ${project.basedir}/src * ``` */ @Parameter(name = "path", required = true) @@ -41,7 +41,7 @@ class SourceLinkMapItem { * Example: * * ```xml - * https://github.com/username/projectname/tree/master/src/main/kotlin + * https://github.com/username/projectname/tree/master/src * ``` */ @Parameter(name = "url", required = true)