diff options
12 files changed, 83 insertions, 13 deletions
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 @@ <toc-element id="dokka-javadoc.md"/> </toc-element> <toc-element id="dokka-plugins.md"/> + <toc-element toc-title="Module documentation" id="dokka-module-and-package-docs.md"/> </chunk> </product-profile> 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 `<module name>`** for a module, and **Package `<package qualified name>`** +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: + +<tabs group="build-script"> +<tab title="Gradle" group-key="gradle"> +Use the <a href="dokka-gradle.md#includes">includes</a> option in <a href="dokka-gradle.md#source-set-configuration">Source set configuration</a>. +</tab> +<tab title="Maven" group-key="mvn"> +Use the <a href="dokka-maven.md#includes">includes</a> option in <a href="dokka-maven.md#general-configuration">General configuration</a>. +</tab> +<tab title="CLI" group-key="cli"> +If you are using command line configuration, use the <a href="dokka-cli.md#includes-cli">includes</a> option in <a href="dokka-cli.md#source-set-options">Source set options</a>. + +If you are using JSON configuration, use the <a href="dokka-cli.md#includes-json">includes</a> option in <a href="dokka-cli.md#general-configuration">General configuration</a>. +</tab> +</tabs> 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. <anchor name="includes-cli"/> | +| `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 <p>Default: <code>false</code></p> </def> <def title="offlineMode"> + <anchor name="includes-json"/> <p>Whether to resolve remote files/links over your network.</p> <p> This includes package-lists used for generating external documentation links. @@ -331,7 +332,7 @@ with [all configuration options](#complete-configuration) applied at the bottom <def title="includes"> <p> A list of Markdown files that contain - <a href="https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation">module and package documentation</a>. + <a href="dokka-module-and-package-docs.md">module and package documentation</a>. </p> <p>The contents of specified files are parsed and embedded into documentation as module and package descriptions.</p> <p>This can be configured on per-package basis.</p> @@ -515,7 +516,7 @@ How to configure Kotlin <def title="includes"> <p> A list of Markdown files that contain - <a href="https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation">module and package documentation</a>. + <a href="dokka-module-and-package-docs.md">module and package documentation</a>. </p> <p>The contents of the specified files are parsed and embedded into documentation as module and package descriptions.</p> </def> 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) { <p>Default: <code>false</code></p> </def> <def title="noAndroidSdkLink"> + <anchor name="includes"/> <p>Whether to generate external documentation links to the Android SDK API reference</p> <p>This is only relevant in Android projects, ignored otherwise.</p> <p>Note: Links <b>are</b> generated when <code>noAndroidSdkLink</code> is set to <code>false</code>.</p> @@ -1030,7 +1031,7 @@ tasks.withType(DokkaTask.class) { <def title="includes"> <p> A list of Markdown files that contain - <a href="https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation">module and package documentation</a>. + <a href="dokka-module-and-package-docs.md">module and package documentation</a>. </p> <p>The contents of the specified files are parsed and embedded into documentation as module and package descriptions.</p> <p> 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 <p>Default: <code>false</code></p> </def> <def title="noJdkLink"> + <anchor name="includes"/> <p>Whether to generate external documentation links to JDK's Javadocs.</p> <p>The version of JDK Javadocs is determined by the <code>jdkVersion</code> option.</p> <p>Note: Links <b>are</b> generated when <code>noJdkLink</code> is set to <code>false</code>.</p> @@ -367,7 +368,7 @@ with [all configuration options](#complete-configuration) applied at the bottom <def title="includes"> <p> A list of Markdown files that contain - <a href="https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation">module and package documentation</a> + <a href="dokka-module-and-package-docs.md">module and package documentation</a> </p> <p>The contents of specified files are parsed and embedded into documentation as module and package descriptions.</p> </def> diff --git a/mkdocs/src/doc/docs/user_guide/applying/gradle.md b/mkdocs/src/doc/docs/user_guide/applying/gradle.md index 435824f9..60ede7b9 100644 --- a/mkdocs/src/doc/docs/user_guide/applying/gradle.md +++ b/mkdocs/src/doc/docs/user_guide/applying/gradle.md @@ -142,7 +142,7 @@ val dokkaHtml by getting(DokkaTask::class) { classpath.from(file("libs/dependency.jar")) // List of files with module and package documentation - // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation + // https://kotlinlang.org/docs/reference/dokka-module-and-package-docs.html includes.from("packages.md", "extra.md") // List of files or directories containing sample code (referenced with @sample tags) diff --git a/mkdocs/src/doc/docs/user_guide/applying/maven.md b/mkdocs/src/doc/docs/user_guide/applying/maven.md index cde6e927..3ea6a56f 100644 --- a/mkdocs/src/doc/docs/user_guide/applying/maven.md +++ b/mkdocs/src/doc/docs/user_guide/applying/maven.md @@ -66,7 +66,7 @@ The available configuration options are shown below: <offlineMode>false</offlineMode> <!-- List of '.md' files with package and module docs --> - <!-- https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation --> + <!-- https://kotlinlang.org/docs/reference/dokka-module-and-package-docs.html --> <includes> <include>packages.md</include> <include>extra.md</include> diff --git a/plugins/base/src/main/kotlin/parsers/moduleAndPackage/parseModuleAndPackageDocumentationFragments.kt b/plugins/base/src/main/kotlin/parsers/moduleAndPackage/parseModuleAndPackageDocumentationFragments.kt index a21a5acb..edfc04a5 100644 --- a/plugins/base/src/main/kotlin/parsers/moduleAndPackage/parseModuleAndPackageDocumentationFragments.kt +++ b/plugins/base/src/main/kotlin/parsers/moduleAndPackage/parseModuleAndPackageDocumentationFragments.kt @@ -31,7 +31,7 @@ private fun parseModuleAndPackageDocFragment( "Package" -> Package else -> throw IllegalStateException( """Unexpected classifier: "${classifierAndName[0]}", expected either "Module" or "Package". - |For more information consult the specification: https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation""".trimMargin() + |For more information consult the specification: https://kotlinlang.org/docs/reference/dokka-module-and-package-docs.html""".trimMargin() ) } diff --git a/plugins/base/src/test/kotlin/transformers/InvalidContentModuleAndPackageDocumentationReaderTest.kt b/plugins/base/src/test/kotlin/transformers/InvalidContentModuleAndPackageDocumentationReaderTest.kt index 6a1f5f11..3c2151d8 100644 --- a/plugins/base/src/test/kotlin/transformers/InvalidContentModuleAndPackageDocumentationReaderTest.kt +++ b/plugins/base/src/test/kotlin/transformers/InvalidContentModuleAndPackageDocumentationReaderTest.kt @@ -74,7 +74,7 @@ class InvalidContentModuleAndPackageDocumentationReaderTest : AbstractContextMod runCatching { readerA[dModule(name = "moduleA", sourceSets = setOf(sourceSetA))] }.exceptionOrNull() assertEquals( "Unexpected classifier: \"Invalid\", expected either \"Module\" or \"Package\". \n" + - "For more information consult the specification: https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation", + "For more information consult the specification: https://kotlinlang.org/docs/reference/dokka-module-and-package-docs.html", exception?.message ) } diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt index c930bc50..2fd452a5 100644 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt +++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTask.kt @@ -19,7 +19,7 @@ abstract class DokkaMultiModuleTask : AbstractDokkaParentTask() { /** * List of Markdown files that contain - * [module and package documentation](https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation). + * [module and package documentation](https://kotlinlang.org/docs/reference/dokka-module-and-package-docs.html). * * Contents of specified files will be parsed and embedded into documentation as module and package descriptions. * diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt index 6390336a..1802a737 100644 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt +++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt @@ -68,7 +68,7 @@ open class GradleDokkaSourceSetBuilder( /** * List of Markdown files that contain - * [module and package documentation](https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation). + * [module and package documentation](https://kotlinlang.org/docs/reference/dokka-module-and-package-docs.html). * * Contents of specified files will be parsed and embedded into documentation as module and package descriptions. * diff --git a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt index 92ab9754..bb955ffd 100644 --- a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt +++ b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt @@ -66,7 +66,7 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List<Dependenc /** * List of Markdown files that contain - * [module and package documentation](https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation). + * [module and package documentation](https://kotlinlang.org/docs/reference/dokka-module-and-package-docs.html). * * Contents of specified files will be parsed and embedded into documentation as module and package descriptions. * |