From 7544a215fb580ae0c47d1f397334f150d1a1ec65 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Tue, 10 Jan 2023 13:14:43 +0100 Subject: Revise documentation (#2728) Co-authored-by: Sarah Haggarty --- docs/topics/runners/dokka-maven.md | 646 +++++++++++++++++++++++++++++++++++++ 1 file changed, 646 insertions(+) create mode 100644 docs/topics/runners/dokka-maven.md (limited to 'docs/topics/runners/dokka-maven.md') diff --git a/docs/topics/runners/dokka-maven.md b/docs/topics/runners/dokka-maven.md new file mode 100644 index 00000000..9bedc517 --- /dev/null +++ b/docs/topics/runners/dokka-maven.md @@ -0,0 +1,646 @@ +[//]: # (title: Maven) + +To generate documentation for a Maven-based project, you can use the Maven plugin for Dokka. + +> Compared to the [Gradle plugin for Dokka](dokka-gradle.md), the Maven plugin 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. + +## Apply Dokka + +To apply Dokka, you need to add `dokka-maven-plugin` to the `plugins` section of your POM file: + +```xml + + + + org.jetbrains.dokka + dokka-maven-plugin + %dokkaVersion% + + + pre-site + + dokka + + + + + + +``` + +## Generate documentation + +The following goals are provided by the Maven plugin: + +### Stable + +| **Goal** | **Description** | +|---------------|----------------------------------------------------------------------------------------| +| `dokka:dokka` | Generates documentation with Dokka plugins applied. [HTML](dokka-html.md) format by default. | + +### Experimental + +| **Goal** | **Description** | +|--------------------|---------------------------------------------------------------------------------------------| +| `dokka:javadoc` | Generates documentation in [Javadoc](dokka-javadoc.md) format. | +| `dokka:javadocJar` | Generates a `javadoc.jar` file that contains documentation in [Javadoc](dokka-javadoc.md) format. | + +### Other output formats + +By default, the Maven plugin for Dokka builds documentation in [HTML](dokka-html.md) output format. + +All other output formats are implemented as [Dokka plugins](dokka-plugins.md). In order to generate documentation in the +desired format, you have to add it as a Dokka plugin to the configuration. + +For example, to use the experimental [GFM](dokka-markdown.md#gfm) format, you have to add `gfm-plugin` artifact: + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + ... + + + + org.jetbrains.dokka + gfm-plugin + %dokkaVersion% + + + + +``` + +With this configuration, running the `dokka:dokka` goal produces documentation in GFM format. + +To learn more about Dokka plugins, see [Dokka plugins](dokka-plugins.md). + +## Build javadoc.jar + +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. + +Unlike the [Gradle plugin for Dokka](dokka-gradle.md#build-javadoc-jar), the Maven plugin comes with a ready-to-use `dokka:javadocJar` +goal. By default, it generates documentation in [Javadoc](dokka-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](dokka-html.md) format instead of Javadoc), similar behavior can be achieved by adding the +Maven JAR plugin with the following configuration: + +```xml + + org.apache.maven.plugins + maven-jar-plugin + 3.3.0 + + + + test-jar + + + + dokka-jar + package + + jar + + + dokka + ${project.build.directory}/dokka + true + + + + +``` + +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 example + +Maven's plugin configuration block can be used to configure Dokka. + +Here is an example of a basic configuration that only changes the output location of your documentation: + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + ... + + ${project.basedir}/target/documentation/dokka + + +``` + +## Configuration options + +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 at the bottom of the page. + +### General configuration + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + + + false + ${project.artifactId} + ${project.basedir}/target/documentation + false + true + false + false + + ${project.basedir}/src + + + PUBLIC + PROTECTED + + false + false + true + + /path/to/dir + /path/to/file + + 8 + 1.7 + 1.7 + false + false + + packages.md + extra.md + + ${project.compileClasspathElements} + + ${project.basedir}/samples + + + + + + + + + + + + +``` + + + +

Whether to skip documentation generation.

+

Default: false

+ + +

The display name used to refer to the project/module. It's used for the table of contents, navigation, logging, etc.

+

Default: {project.artifactId}

+ + +

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

+

Default: {project.basedir}/target/dokka

+ + +

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

+

Default: false

+ + +

Whether to suppress obvious functions.

+

+ A function is considered to be obvious if it is: + +

  • + Inherited from kotlin.Any, Kotlin.Enum, java.lang.Object or + java.lang.Enum, such as equals, hashCode, toString. +
    • +
  • + Synthetic (generated by the compiler) and does not have any documentation, such as + dataClass.componentN or dataClass.copy. +
    • + +

    +

    Default: true

    +     + +

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

    +

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

    +

    Default: false

    +     + +

    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 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 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 section. +

    +

    Default: false

    +     + +

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

    +

    Default: {project.compileSourceRoots}

    +     + +

    The set of visibility modifiers that should be documented.

    +

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

    +

    Default: PUBLIC

    +     + +

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

    +

    Default: false

    +     + +

    Whether to document declarations annotated with @Deprecated.

    +

    This can be overridden at package level.

    +

    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 to be empty. +

    +

    Default: true

    +     + +

    + The directories or individual files that should be suppressed, meaning that declarations from them + are not documented. +

    +     + +

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

    +

    + 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

    +     + +

    + The Kotlin language version + used for setting up analysis and @sample + environment. +

    +

    By default, the latest language version available to Dokka's embedded compiler is used.

    +     + +

    + The Kotlin API version + used for setting up analysis and @sample + environment. +

    +

    By default, it is deduced from languageVersion.

    +     + +

    + Whether to generate external documentation links that lead to the API reference + documentation of Kotlin's standard library. +

    +

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

    +

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

    +     + +

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

    +

    Default: {project.compileClasspathElements}

    +     + +

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

    +     +     + +### Source link configuration + +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 the documentation for the +[`count()`](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/count.html) +function in `kotlinx.coroutines`. + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + + + + + ${project.basedir}/src + https://github.com/kotlin/dokka/tree/master/src + #L + + + + +``` + + + +

    + The path to the local source directory. The path must be relative to the root of the + current module. +

    +     + +

    + 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 suffix used to append 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 option is set + to #L and the line number is 10, the resulting URL suffix is #L10. +

    +

    + Suffixes used by popular services: + +

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

    +     +     + +#### External documentation links configuration + +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 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 + + org.jetbrains.dokka + dokka-maven-plugin + + + + + https://kotlinlang.org/api/kotlinx.serialization/ + file:/${project.basedir}/serialization.package.list + + + + +``` + + + +

    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, + and link declarations together. +

    +

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

    +     + +

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

    +     +     + +### Package options + +The `perPackageOptions` configuration block allows setting some options for specific packages matched by `matchingRegex`. + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + + + + + .*api.* + false + false + false + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + + + + + +``` + + + +

    The regular expression that is used to match the package.

    +

    Default: .*

    +     + +

    Whether this package should be skipped when generating documentation.

    +

    Default: false

    +     + +

    The set of visibility modifiers that should be documented.

    +

    + 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

    +     + +

    Whether to document declarations annotated with @Deprecated.

    +

    This can be set on project/module level.

    +

    Default: false

    +     + +

    + 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

    +     +     + +### Complete configuration + +Below you can see all the possible configuration options applied at the same time. + +```xml + + org.jetbrains.dokka + dokka-maven-plugin + + + false + ${project.artifactId} + ${project.basedir}/target/documentation + false + true + false + false + + ${project.basedir}/src + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + + false + false + true + + /path/to/dir + /path/to/file + + 8 + 1.7 + 1.7 + false + false + + packages.md + extra.md + + ${project.compileClasspathElements} + + ${project.basedir}/samples + + + + ${project.basedir}/src + https://github.com/kotlin/dokka/tree/master/src + #L + + + + + https://kotlinlang.org/api/latest/jvm/stdlib/ + file:/${project.basedir}/stdlib.package.list + + + + + .*api.* + false + false + false + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + + + + + +``` -- cgit