From 1dcb0f88bbe78a10c2de8b97ebf797e7af8b90e0 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty <81160244+sarahhaggarty@users.noreply.github.com> Date: Thu, 19 Jan 2023 17:34:28 +0100 Subject: Add module and package documentation content (#2819) Co-authored-by: Sarah Haggarty --- docs/dokka.tree | 1 + docs/topics/dokka-module-and-package-docs.md | 66 ++++++++++++++++++++++++++++ docs/topics/runners/dokka-cli.md | 9 ++-- docs/topics/runners/dokka-gradle.md | 3 +- docs/topics/runners/dokka-maven.md | 3 +- 5 files changed, 76 insertions(+), 6 deletions(-) create mode 100644 docs/topics/dokka-module-and-package-docs.md (limited to 'docs') diff --git a/docs/dokka.tree b/docs/dokka.tree index 73ac277e..4cc096ac 100644 --- a/docs/dokka.tree +++ b/docs/dokka.tree @@ -20,5 +20,6 @@ + diff --git a/docs/topics/dokka-module-and-package-docs.md b/docs/topics/dokka-module-and-package-docs.md new file mode 100644 index 00000000..edfa150f --- /dev/null +++ b/docs/topics/dokka-module-and-package-docs.md @@ -0,0 +1,66 @@ +[//]: # (title: Module documentation) + +Documentation for a module as a whole, as well as packages in that module, can be provided as separate Markdown files. + +## File format + +Inside the Markdown file, the documentation for the module as a whole and for individual packages is introduced by the corresponding +first-level headings. The text of the heading **must** be **Module ``** for a module, and **Package ``** +for a package. + +The file doesn't have to contain both module and package documentation. You can have files that contain only package or +module documentation. You can even have a Markdown file per module or package. + +Using [Markdown syntax](https://www.markdownguide.org/basic-syntax/), you can add: +* Headings up to level 6 +* Emphasis with bold or italic formatting +* Links +* Inline code +* Code blocks +* Blockquotes + +Here's an example file containing both module and package documentation: + +```text +# Module kotlin-demo + +This content appears under your module name. + +# Package org.jetbrains.kotlin.demo + +This content appears under your package name in the packages list. +It also appears under the first-level heading on your package's page. + +## Level 2 heading for package org.jetbrains.kotlin.demo + +Content after this heading is also part of documentation for org.jetbrains.kotlin.demo + +# Package org.jetbrains.kotlin.demo2 + +This content appears under your package name in the packages list. +It also appears under the first-level heading on your package's page. + +## Level 2 heading for package org.jetbrains.kotlin.demo + +Content after this heading is also part of documentation for `org.jetbrains.kotlin.demo2` +``` + +To explore an example project with Gradle, see [Dokka gradle example](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example). + +## Pass files to Dokka + +To pass these files to Dokka, you need to use the relevant **includes** option for Gradle, Maven, or CLI: + + + +Use the includes option in Source set configuration. + + +Use the includes option in General configuration. + + +If you are using command line configuration, use the includes option in Source set options. + +If you are using JSON configuration, use the includes option in General configuration. + + diff --git a/docs/topics/runners/dokka-cli.md b/docs/topics/runners/dokka-cli.md index fa8fa459..7d76eefd 100644 --- a/docs/topics/runners/dokka-cli.md +++ b/docs/topics/runners/dokka-cli.md @@ -204,8 +204,8 @@ Short summary: | `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 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. | +| `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](dokka-module-and-package-docs.md). Accepts multiple paths separated by semicolons. | | `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. | @@ -312,6 +312,7 @@ with [all configuration options](#complete-configuration) applied at the bottom

Default: false

+

Whether to resolve remote files/links over your network.

This includes package-lists used for generating external documentation links. @@ -331,7 +332,7 @@ with [all configuration options](#complete-configuration) applied at the bottom

A list of Markdown files that contain - module and package documentation. + module and package documentation.

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

This can be configured on per-package basis.

@@ -515,7 +516,7 @@ How to configure Kotlin

A list of Markdown files that contain - module and package documentation. + module and package documentation.

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

 diff --git a/docs/topics/runners/dokka-gradle.md b/docs/topics/runners/dokka-gradle.md index c049b225..f81ffe1d 100644 --- a/docs/topics/runners/dokka-gradle.md +++ b/docs/topics/runners/dokka-gradle.md @@ -1022,6 +1022,7 @@ tasks.withType(DokkaTask.class) {

Default: false

 +

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

This is only relevant in Android projects, ignored otherwise.

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

@@ -1030,7 +1031,7 @@ tasks.withType(DokkaTask.class) {

A list of Markdown files that contain - module and package documentation. + module and package documentation.

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

diff --git a/docs/topics/runners/dokka-maven.md b/docs/topics/runners/dokka-maven.md index 252abb6f..3331bce1 100644 --- a/docs/topics/runners/dokka-maven.md +++ b/docs/topics/runners/dokka-maven.md @@ -359,6 +359,7 @@ with [all configuration options](#complete-configuration) applied at the bottom

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.

@@ -367,7 +368,7 @@ with [all configuration options](#complete-configuration) applied at the bottom

A list of Markdown files that contain - module and package documentation + module and package documentation

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

 -- cgit