From 6de36eea0a0b87fcb776ff611335f22fe72644fc Mon Sep 17 00:00:00 2001 From: "ying.li" Date: Tue, 25 Apr 2023 02:35:00 +0900 Subject: [PATCH 1/2] minor fix for document --- docs/topics/dokka-module-and-package-docs.md | 4 +- docs/topics/dokka-plugins.md | 46 ++++++++++---------- docs/topics/formats/dokka-javadoc.md | 2 +- docs/topics/formats/dokka-markdown.md | 3 +- docs/topics/runners/dokka-cli.md | 14 +++--- docs/topics/runners/dokka-gradle.md | 16 +++---- docs/topics/runners/dokka-maven.md | 12 ++--- 7 files changed, 49 insertions(+), 48 deletions(-) diff --git a/docs/topics/dokka-module-and-package-docs.md b/docs/topics/dokka-module-and-package-docs.md index d8ceb3fa5d..9bf786198e 100644 --- a/docs/topics/dokka-module-and-package-docs.md +++ b/docs/topics/dokka-module-and-package-docs.md @@ -33,14 +33,14 @@ 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 +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 +## Level 2 heading for package org.jetbrains.kotlin.demo2 Content after this heading is also part of documentation for `org.jetbrains.kotlin.demo2` ``` diff --git a/docs/topics/dokka-plugins.md b/docs/topics/dokka-plugins.md index d8d9d24992..2945869d16 100644 --- a/docs/topics/dokka-plugins.md +++ b/docs/topics/dokka-plugins.md @@ -112,13 +112,13 @@ If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), ```json { - ... - "pluginsClasspath": [ - "./dokka-base-%dokkaVersion%.jar", - "...", - "./mathjax-plugin-%dokkaVersion%.jar" - ], - ... + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./mathjax-plugin-%dokkaVersion%.jar" + ], + ... } ``` @@ -168,9 +168,9 @@ import org.jetbrains.dokka.gradle.DokkaTask tasks.withType().configureEach { val dokkaBaseConfiguration = """ { - "customAssets": ["${file("assets/my-image.png")}"], - "customStyleSheets": ["${file("assets/my-styles.css")}"], - "footerMessage": "(c) 2022 MyOrg" + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" } """ pluginsMapConfiguration.set( @@ -191,14 +191,14 @@ import org.jetbrains.dokka.gradle.DokkaTask tasks.withType(DokkaTask.class) { String dokkaBaseConfiguration = """ { - "customAssets": ["${file("assets/my-image.png")}"], - "customStyleSheets": ["${file("assets/my-styles.css")}"], - "footerMessage": "(c) 2022 MyOrg" + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" } """ pluginsMapConfiguration.set( - // fully qualified plugin name to json configuration - ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] + // fully qualified plugin name to json configuration + ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] ) } ``` @@ -248,14 +248,14 @@ If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), ```json { - "moduleName": "Dokka Example", - "pluginsConfiguration": [ - { - "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", - "serializationFormat": "JSON", - "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}" - } - ] + "moduleName": "Dokka Example", + "pluginsConfiguration": [ + { + "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", + "serializationFormat": "JSON", + "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}" + } + ] } ``` diff --git a/docs/topics/formats/dokka-javadoc.md b/docs/topics/formats/dokka-javadoc.md index e9d4a6f1ef..9ea78fd970 100644 --- a/docs/topics/formats/dokka-javadoc.md +++ b/docs/topics/formats/dokka-javadoc.md @@ -1,6 +1,6 @@ [//]: # (title: Javadoc) -> The Javadoc output format is still in Alpha so you may find bugs and experience migration issues when using it. +> The Javadoc output format is still in Alpha, so you may find bugs and experience migration issues when using it. > Successful integration with tools that accept Java's Javadoc HTML as input is not guaranteed. > **You use it at your own risk.** > diff --git a/docs/topics/formats/dokka-markdown.md b/docs/topics/formats/dokka-markdown.md index d4919a5c3c..0c863f3561 100644 --- a/docs/topics/formats/dokka-markdown.md +++ b/docs/topics/formats/dokka-markdown.md @@ -1,6 +1,7 @@ [//]: # (title: Markdown) -> The Markdown output formats are still in Alpha so you may find bugs and experience migration issues when using them. **You use them at your own risk.** +> The Markdown output formats are still in Alpha, so you may find bugs and experience migration issues when using them. +> **You use them at your own risk.** > {type="warning"} diff --git a/docs/topics/runners/dokka-cli.md b/docs/topics/runners/dokka-cli.md index 7d76eefd15..ddaf3bbd9e 100644 --- a/docs/topics/runners/dokka-cli.md +++ b/docs/topics/runners/dokka-cli.md @@ -203,7 +203,7 @@ Short 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 the dependent source sets in format `moduleName/sourceSetName`. Accepts multiple paths separated by semicolons. | +| `dependentSourceSets` | Names of the dependent source sets in format `moduleName/sourceSetName`. Accepts multiple values 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`. | @@ -436,8 +436,8 @@ How to configure Kotlin

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

This can be configured on per-package basis.

@@ -674,17 +674,17 @@ You can add package configurations for all source sets together at the same time

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

 -### External documentation configuration +### External documentation links configuration -The `externalDocumentationLink` block allows the creation of links that lead to the externally hosted documentation of +The `externalDocumentationLinks` 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 diff --git a/docs/topics/runners/dokka-gradle.md b/docs/topics/runners/dokka-gradle.md index ae8b003bdb..51f270a843 100644 --- a/docs/topics/runners/dokka-gradle.md +++ b/docs/topics/runners/dokka-gradle.md @@ -36,7 +36,7 @@ plugins { -When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply the Gradle plugin for Dokka +When documenting [multi-project](#multi-project-builds) builds, you need to apply the Gradle plugin for Dokka within subprojects as well. You can use `allprojects {}` or `subprojects {}` Gradle configurations to achieve that: @@ -451,8 +451,8 @@ plugins { tasks.withType(DokkaTask.class) { dokkaSourceSets.configureEach { documentedVisibilities.set([ - DokkaConfiguration.Visibility.PUBLIC, - DokkaConfiguration.Visibility.PROTECTED + Visibility.PUBLIC, + Visibility.PROTECTED ]) perPackageOption { @@ -942,8 +942,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, - 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, + as well as if you want to exclude public declarations and only document internal API.

This can be configured on per-package basis.

Default: DokkaConfiguration.Visibility.PUBLIC

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

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

+

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.

Default: false

@@ -1272,8 +1272,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 this 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

diff --git a/docs/topics/runners/dokka-maven.md b/docs/topics/runners/dokka-maven.md index 3331bce132..14551c91d3 100644 --- a/docs/topics/runners/dokka-maven.md +++ b/docs/topics/runners/dokka-maven.md @@ -288,8 +288,8 @@ with [all configuration options](#complete-configuration) applied at the bottom

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

@@ -450,9 +450,9 @@ function in `kotlinx.coroutines`. -#### External documentation links configuration +### External documentation links configuration -The `externalDocumentationLink` block allows the creation of links that lead to the externally hosted documentation of +The `externalDocumentationLinks` 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 @@ -545,8 +545,8 @@ The `perPackageOptions` configuration block allows setting some options for spec

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

 From 63ca2b6b3070be7239a8a27c7583417c7e02816b Mon Sep 17 00:00:00 2001 From: "ying.li" Date: Wed, 26 Apr 2023 14:43:35 +0900 Subject: [PATCH 2/2] revert unnecessary changes for ident --- docs/topics/dokka-plugins.md | 46 ++++++++++++++--------------- docs/topics/runners/dokka-gradle.md | 4 +-- 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/topics/dokka-plugins.md b/docs/topics/dokka-plugins.md index 2945869d16..d8d9d24992 100644 --- a/docs/topics/dokka-plugins.md +++ b/docs/topics/dokka-plugins.md @@ -112,13 +112,13 @@ If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), ```json { - ... - "pluginsClasspath": [ - "./dokka-base-%dokkaVersion%.jar", - "...", - "./mathjax-plugin-%dokkaVersion%.jar" - ], - ... + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./mathjax-plugin-%dokkaVersion%.jar" + ], + ... } ``` @@ -168,9 +168,9 @@ import org.jetbrains.dokka.gradle.DokkaTask tasks.withType().configureEach { val dokkaBaseConfiguration = """ { - "customAssets": ["${file("assets/my-image.png")}"], - "customStyleSheets": ["${file("assets/my-styles.css")}"], - "footerMessage": "(c) 2022 MyOrg" + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" } """ pluginsMapConfiguration.set( @@ -191,14 +191,14 @@ import org.jetbrains.dokka.gradle.DokkaTask tasks.withType(DokkaTask.class) { String dokkaBaseConfiguration = """ { - "customAssets": ["${file("assets/my-image.png")}"], - "customStyleSheets": ["${file("assets/my-styles.css")}"], - "footerMessage": "(c) 2022 MyOrg" + "customAssets": ["${file("assets/my-image.png")}"], + "customStyleSheets": ["${file("assets/my-styles.css")}"], + "footerMessage": "(c) 2022 MyOrg" } """ pluginsMapConfiguration.set( - // fully qualified plugin name to json configuration - ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] + // fully qualified plugin name to json configuration + ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] ) } ``` @@ -248,14 +248,14 @@ If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), ```json { - "moduleName": "Dokka Example", - "pluginsConfiguration": [ - { - "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", - "serializationFormat": "JSON", - "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}" - } - ] + "moduleName": "Dokka Example", + "pluginsConfiguration": [ + { + "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", + "serializationFormat": "JSON", + "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}" + } + ] } ``` diff --git a/docs/topics/runners/dokka-gradle.md b/docs/topics/runners/dokka-gradle.md index 51f270a843..a328729377 100644 --- a/docs/topics/runners/dokka-gradle.md +++ b/docs/topics/runners/dokka-gradle.md @@ -451,8 +451,8 @@ plugins { tasks.withType(DokkaTask.class) { dokkaSourceSets.configureEach { documentedVisibilities.set([ - Visibility.PUBLIC, - Visibility.PROTECTED + Visibility.PUBLIC, + Visibility.PROTECTED ]) perPackageOption {