diff options
| -rw-r--r-- | README.md | 18 | ||||
| -rw-r--r-- | docs/src/doc/docs/developer_guide/data_model.md | 2 | ||||
| -rw-r--r-- | docs/src/doc/docs/developer_guide/extension_points.md | 4 | ||||
| -rw-r--r-- | docs/src/doc/docs/developer_guide/introduction.md | 6 | ||||
| -rw-r--r-- | docs/src/doc/docs/index.md | 4 | ||||
| -rw-r--r-- | docs/src/doc/docs/user_guide/cli/usage.md | 6 | ||||
| -rw-r--r-- | docs/src/doc/docs/user_guide/gradle/usage.md | 16 | ||||
| -rw-r--r-- | docs/src/doc/docs/user_guide/introduction.md | 8 | ||||
| -rw-r--r-- | docs/src/doc/mkdocs.yml | 2 |
9 files changed, 33 insertions, 33 deletions
@@ -1,20 +1,20 @@ -# dokka [](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [/statusIcon)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv) +# Dokka [](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [/statusIcon)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv) Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java. Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands standard Javadoc comments in Java files and [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in Kotlin files, and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown. -## Using dokka +## Using Dokka **Full documentation is available at [http://kotlin.github.io/dokka](http://kotlin.github.io/dokka)** ### Using the Gradle plugin -_Note: If you are upgrading from 0.10.x to a current release of dokka, please have a look at our +_Note: If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our [migration guide](runners/gradle-plugin/MIGRATION.md)_ -The preferred way is to use `plugins` block. Since dokka is currently not published to the Gradle plugin portal, -you not only need to add `dokka` to the `build.gradle.kts` file, but you also need to modify the `settings.gradle.kts` file: +The preferred way is to use `plugins` block. Since Dokka is currently not published to the Gradle plugin portal, +you not only need to add `org.jetbrains.dokka` to the `build.gradle.kts` file, but you also need to modify the `settings.gradle.kts` file: build.gradle.kts: ```kotlin @@ -48,7 +48,7 @@ dependencies { } ``` -You can also create a custom dokka task and add plugins directly inside: +You can also create a custom Dokka task and add plugins directly inside: ```kotlin val customDokkaTask by creating(DokkaTask::class) { @@ -70,7 +70,7 @@ Please see the [Dokka Gradle example project](https://github.com/Kotlin/kotlin-e #### Android -Make sure you apply dokka after `com.android.library` and `kotlin-android`. +Make sure you apply Dokka after `com.android.library` and `kotlin-android`. ```kotlin buildscript { @@ -110,7 +110,7 @@ tasks.dokkaHtmlMultiModule.configure { } ``` -`DokkaMultiModule` depends on all dokka tasks in the subprojects, runs them, and creates a toplevel page (based on the `documentationFile`) +`DokkaMultiModule` depends on all Dokka tasks in the subprojects, runs them, and creates a toplevel page (based on the `documentationFile`) with links to all generated (sub)documentations ### Using the Maven plugin @@ -189,7 +189,7 @@ You can also use a JSON file with dokka configuration: * `jekyll` - Jekyll compatible markdown If you want to generate the documentation as seen from Java perspective, you can add the `kotlin-as-java` plugin -to the dokka plugins classpath, eg. in Gradle: +to the Dokka plugins classpath, eg. in Gradle: ```kotlin dependencies{ diff --git a/docs/src/doc/docs/developer_guide/data_model.md b/docs/src/doc/docs/developer_guide/data_model.md index 45200004..3da3f98e 100644 --- a/docs/src/doc/docs/developer_guide/data_model.md +++ b/docs/src/doc/docs/developer_guide/data_model.md @@ -1,6 +1,6 @@ # Dokka Data Model -There a four data models that dokka uses: Documentable Model, Documentation Model, Page Model and Content Model. +There a four data models that Dokka uses: Documentable Model, Documentation Model, Page Model and Content Model. ## Documentable Model diff --git a/docs/src/doc/docs/developer_guide/extension_points.md b/docs/src/doc/docs/developer_guide/extension_points.md index ca552c3b..b121c3f7 100644 --- a/docs/src/doc/docs/developer_guide/extension_points.md +++ b/docs/src/doc/docs/developer_guide/extension_points.md @@ -121,7 +121,7 @@ interface Renderer { } ``` -By default, only `HtmlRenderer`, that extends basic `DefaultRenderer`, is created, but it will be registered only if configuration parameter `format` is set to `html`. Using any other value without providing valid renderer will cause dokka to fail. +By default, only `HtmlRenderer`, that extends basic `DefaultRenderer`, is created, but it will be registered only if configuration parameter `format` is set to `html`. Using any other value without providing valid renderer will cause Dokka to fail. ## Multimodule page generation endpoints @@ -151,7 +151,7 @@ This step uses `CoreExtensions.allModulePageTransformer` entry point. All extens ## Default extensions' extension points -Default core extension points already have an implementation for providing basic dokka functionality. All of them are declared in `DokkaBase` plugin. If you don't want this default extensions to load, all you need to do is not load dokka base and load your plugin instead. +Default core extension points already have an implementation for providing basic Dokka functionality. All of them are declared in `DokkaBase` plugin. If you don't want this default extensions to load, all you need to do is not load Dokka base and load your plugin instead. ```kotlin val customPlugin by configurations.creating diff --git a/docs/src/doc/docs/developer_guide/introduction.md b/docs/src/doc/docs/developer_guide/introduction.md index c69d71e1..ba5f8bdc 100644 --- a/docs/src/doc/docs/developer_guide/introduction.md +++ b/docs/src/doc/docs/developer_guide/introduction.md @@ -1,9 +1,9 @@ # Guide to Dokka Plugin development -## Building dokka +## Building Dokka Dokka is built with Gradle. To build it, use `./gradlew build`. -Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run dokka. +Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run Dokka. Here's how to import and configure Dokka in IntelliJ IDEA 2019.3: @@ -42,7 +42,7 @@ tasks.withType<KotlinCompile> { ## Building sample plugin -In order to load a plugin into dokka, your class must extend `DokkaPlugin` class. All instances are automatically loaded during dokka setup using `java.util.ServiceLoader`. +In order to load a plugin into Dokka, your class must extend `DokkaPlugin` class. All instances are automatically loaded during Dokka setup using `java.util.ServiceLoader`. Dokka provides a set of entry points, for which user can create their own implementations. They must be delegated using `DokkaPlugin.extending(definition: ExtendingDSL.() -> Extension<T, *, *>)` function,that returns a delegate `ExtensionProvider` with supplied definition. diff --git a/docs/src/doc/docs/index.md b/docs/src/doc/docs/index.md index 9472d738..d730e11d 100644 --- a/docs/src/doc/docs/index.md +++ b/docs/src/doc/docs/index.md @@ -1,4 +1,4 @@ -# dokka [](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [/statusIcon)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv) +# Dokka [](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [/statusIcon)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv) Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java. Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands @@ -13,4 +13,4 @@ Dokka provides support for the following build systems: * [Command line](user_guide/cli/usage.md) !!! note - The Gradle plugin is the preferred way to use dokka + The Gradle plugin is the preferred way to use Dokka diff --git a/docs/src/doc/docs/user_guide/cli/usage.md b/docs/src/doc/docs/user_guide/cli/usage.md index 9fdc6a24..36b0a549 100644 --- a/docs/src/doc/docs/user_guide/cli/usage.md +++ b/docs/src/doc/docs/user_guide/cli/usage.md @@ -13,7 +13,7 @@ Dokka supports the following command line arguments: * `-outputDir` - the output directory where the documentation is generated * `-moduleName` - (required) - module name used as a part of source set ID when declaring dependent source sets * `-cacheRoot` - cache directory to enable package-list caching - * `-pluginsClasspath` - artifacts with dokka plugins, separated by `;`. At least dokka base and all its dependencies must be added there + * `-pluginsClasspath` - artifacts with Dokka plugins, separated by `;`. At least `dokka-base` and all its dependencies must be added there * `-offlineMode` - do not resolve package-lists online * `-failOnWarning` - throw an exception instead of a warning * `-globalPackageOptions` - per package options added to all source sets @@ -39,10 +39,10 @@ Dokka supports the following command line arguments: * `-analysisPlatform` - platform used for analysis, see the [Platforms](#platforms) section * `-dependentSourceSets` - list of dependent source sets in format `moduleName/sourceSetName`, separated by `;` -You can also use a JSON file with dokka configuration: +You can also use a JSON file with Dokka configuration: ``` java -jar <dokka_cli.jar> <path_to_config.json> ``` ## Applying plugins -To apply a dokka plugin you have to provide it and all its dependencies in the `pluginsClasspath` parameter +To apply a Dokka plugin you have to provide it and all its dependencies in the `pluginsClasspath` parameter diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md index 06af7174..130d3de5 100644 --- a/docs/src/doc/docs/user_guide/gradle/usage.md +++ b/docs/src/doc/docs/user_guide/gradle/usage.md @@ -1,10 +1,10 @@ # Using the Gradle plugin !!! important - If you are upgrading from 0.10.x to a current release of dokka, please have a look at our + If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our [migration guide](https://github.com/Kotlin/dokka/blob/master/runners/gradle-plugin/MIGRATION.md) -The preferred way is to use `plugins` block. Since dokka is currently not published to the Gradle plugin portal, +The preferred way is to use `plugins` block. Since Dokka is currently not published to the Gradle plugin portal, you not only need to add `dokka` to the `build.gradle.kts` file, but you also need to modify the `settings.gradle.kts` file: build.gradle.kts: @@ -53,9 +53,9 @@ The plugin adds `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll` tasks Each task corresponds to one output format, so you should run `dokkaGfm` when you want to have a documentation in `GFM` format. Output formats are explained in [the introduction](../introduction.md#output-formats) -If you encounter any problems when migrating from older versions of dokka, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). +If you encounter any problems when migrating from older versions of Dokka, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). -Minimal dokka configuration (with only custom output directory) +Minimal configuration (with custom output directory only): Kotlin ```kotlin @@ -188,7 +188,7 @@ dokkaHtml { ## Multiplatform Dokka supports single-platform and multi-platform projects using source sets abstraction. For most mutli-platform projects -you should assume that dokka's source sets correspond to Kotlin plugin's source sets. All source sets are by default registered +you should assume that Dokka's source sets correspond to Kotlin plugin's source sets. All source sets are by default registered and configured automatically although test source sets are suppressed Kotlin @@ -230,7 +230,7 @@ dependencies { } ``` -You can also create a custom dokka task and add plugins directly inside: +You can also create a custom Dokka task and add plugins directly inside: ```kotlin val customDokkaTask by creating(DokkaTask::class) { @@ -252,7 +252,7 @@ To generate the documentation, use the appropriate `dokka${format}` Gradle task: ## Android !!! important - Make sure you apply dokka after `com.android.library` and `kotlin-android`. + Make sure you apply Dokka after `com.android.library` and `kotlin-android`. ```kotlin buildscript { @@ -292,7 +292,7 @@ tasks.dokkaHtmlMultiModule.configure { } ``` -`DokkaMultiModule` depends on all dokka tasks in the subprojects, runs them, and creates a toplevel page (based on the `documentationFile`) +`DokkaMultiModule` depends on all Dokka tasks in the subprojects, runs them, and creates a toplevel page (based on the `documentationFile`) with links to all generated (sub)documentations ## Example project diff --git a/docs/src/doc/docs/user_guide/introduction.md b/docs/src/doc/docs/user_guide/introduction.md index 1add9e9f..0de6a5ef 100644 --- a/docs/src/doc/docs/user_guide/introduction.md +++ b/docs/src/doc/docs/user_guide/introduction.md @@ -5,13 +5,13 @@ Dokka can be customized with plugins. Each output format is internally a plugin. Additionally, `kotlin-as-java` plugin can be used to generate documentation as seen from Java perspective. Currently maintained plugins are: -* `dokka-base` - the main plugin needed to run dokka, contains html format +* `dokka-base` - the main plugin needed to run Dokka, contains html format * `gfm-plugin` - configures `GFM` output format * `jekyll-plugin` - configures `Jekyll` output format * `javadoc-plugin` - configures `Javadoc` output format, automatically applies `kotlin-as-java-plugin` * `kotlin-as-java-plugin` - translates Kotlin definitions to Java -Please see the usage instructions for each build system on how to add plugins to dokka. +Please see the usage instructions for each build system on how to add plugins to Dokka. ## Source sets Dokka generates documentation based on source sets. @@ -53,7 +53,7 @@ kotlin { // Kotlin plugin configuration * `jekyll` - Jekyll compatible markdown If you want to generate the documentation as seen from Java perspective, you can add the `kotlin-as-java` plugin -to the dokka plugins classpath, eg. in Gradle: +to the Dokka plugins classpath, eg. in Gradle: ```kotlin dependencies{ @@ -64,7 +64,7 @@ dependencies{ ## Platforms -Each dokka source set is analyzed for a specific platform. The platform should be extracted automatically from the Kotlin plugin. +Each Dokka source set is analyzed for a specific platform. The platform should be extracted automatically from the Kotlin plugin. In case of a manual source set configuration, you have to select one of the following: * `jvm` diff --git a/docs/src/doc/mkdocs.yml b/docs/src/doc/mkdocs.yml index fd226c61..9b113caa 100644 --- a/docs/src/doc/mkdocs.yml +++ b/docs/src/doc/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: dokka +site_name: Dokka # Meta tags (placed in header) site_description: Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java |