From 5eeb2bbeb8c71ae813808ee0e8d09293c4abe1c1 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 19 Jan 2023 04:10:57 +0100 Subject: Revise README documentation for examples and plugins (#2736) --- .github/workflows/dokka-examples.yml | 2 - .github/workflows/gh-pages-examples.yml | 5 +- CONTRIBUTING.md | 116 +- examples/README.md | 25 + examples/gradle/README.md | 11 + .../gradle/dokka-customFormat-example/README.md | 23 +- .../dokka-customFormat-example/build.gradle.kts | 12 +- .../gradle/dokka-customFormat-example/demo.png | Bin 0 -> 77918 bytes examples/gradle/dokka-gradle-example/README.md | 22 + .../gradle/dokka-gradle-example/build.gradle.kts | 6 + examples/gradle/dokka-gradle-example/demo.png | Bin 0 -> 71039 bytes .../gradle/dokka-kotlinAsJava-example/README.md | 19 + .../dokka-kotlinAsJava-example/build.gradle.kts | 2 +- .../gradle/dokka-kotlinAsJava-example/demo.png | Bin 0 -> 101974 bytes .../dokka-library-publishing-example/README.md | 41 + .../gradle/dokka-multimodule-example/README.md | 25 + examples/gradle/dokka-multimodule-example/demo.png | Bin 0 -> 93395 bytes .../dokka-multimodule-example/gradle.properties | 2 + .../parentProject/build.gradle.kts | 35 +- .../parentProject/childProjectA/Module.md | 5 - .../parentProject/childProjectA/ModuleA.md | 5 + .../parentProject/childProjectA/build.gradle.kts | 4 +- .../parentProject/childProjectB/Module.md | 5 - .../parentProject/childProjectB/ModuleB.md | 5 + .../parentProject/childProjectB/build.gradle.kts | 4 +- .../dokka-multimodule-example/settings.gradle.kts | 7 +- .../gradle/dokka-multiplatform-example/README.md | 29 + .../dokka-multiplatform-example/build.gradle.kts | 8 +- .../gradle/dokka-multiplatform-example/demo.png | Bin 0 -> 183500 bytes .../dokka-multiplatform-example/gradle.properties | 1 - .../kotlin/org.kotlintestmpp.common/main.kt | 4 - .../org/kotlintestmpp/CommonCoroutineExtensions.kt | 15 + .../kotlin/org/kotlintestmpp/CommonDateUtils.kt | 14 + .../kotlin/org/kotlintestmpp/common/Foo.kt | 7 + .../kotlin/org/kotlintestmpp/coroutines.kt | 6 - .../kotlin/org/kotlintestmpp/getCurrentDate.kt | 8 - .../customJdk9/kotlin/demo/CustomSourceSetFile.kt | 11 - .../org/kotlintest/jdk9/CustomSourceSetFile.kt | 11 + .../org/kotlintestmpp/JsCoroutineExtensions.kt | 11 + .../jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt | 8 + .../jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt | 18 + .../kotlin/org/kotlintestmpp/asyncWithDealy.kt | 8 - .../src/jsMain/kotlin/org/kotlintestmpp/main.kt | 17 - .../src/jsMain/kotlin/shouldbesuppressed/supp.kt | 11 - .../kotlin/org/kotlintestmpp/JavaAnnotation.java | 19 + .../org/kotlintestmpp/JvmCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/JvmDateUtils.kt | 8 + .../kotlin/org/kotlintestmpp/JvmFunctions.kt | 35 + .../kotlin/org/kotlintestmpp/MainCommand.java | 16 - .../kotlin/org/kotlintestmpp/asyncWithDealy.kt | 8 - .../src/jvmMain/kotlin/org/kotlintestmpp/main.kt | 30 - .../src/jvmMain/kotlin/shouldbesuppressed/supp.kt | 11 - .../linuxMain/kotlin/org/kotlintestmpp/CInterop.kt | 13 + .../org/kotlintestmpp/LinuxCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/LinuxDateUtils.kt | 8 + .../kotlin/org/kotlintestmpp/asyncWithDealy.kt | 8 - .../linuxMain/kotlin/org/kotlintestmpp/cinterop.kt | 10 - .../kotlin/org/kotlintestmpp/getCurrentDate.kt | 8 - .../org/kotlintestmpp/MacOsCoroutineExtensions.kt | 11 + .../kotlin/org/kotlintestmpp/MacOsDateUtils.kt | 8 + .../kotlin/org/kotlintestmpp/asyncWithDealy.kt | 8 - .../kotlin/org/kotlintestmpp/getCurrentDate.kt | 8 - .../dokka-versioning-multimodule-example/README.md | 25 + .../build.gradle.kts | 2 +- .../dokka-versioning-multimodule-example/demo.png | Bin 0 -> 35812 bytes .../parentProject/build.gradle.kts | 38 +- .../src/main/kotlin/demo/ChildProjectAClass.kt | 14 +- .../childProjectA/src/main/kotlin/demo/FancyAPI.kt | 10 + .../src/main/kotlin/demo/ChildProjectBClass.kt | 4 +- .../src/main/kotlin/demo/Functions.kt | 8 + .../-child-project-a-class.html | 64 + .../demo/-child-project-a-class/index.html | 86 ++ .../0.9/childProjectA/demo/index.html | 85 ++ .../0.9/childProjectA/index.html | 79 ++ .../0.9/childProjectA/navigation.html | 32 + .../-child-project-b-class.html | 64 + .../demo/-child-project-b-class/index.html | 86 ++ .../0.9/childProjectB/demo/index.html | 85 ++ .../0.9/childProjectB/index.html | 79 ++ .../0.9/childProjectB/navigation.html | 32 + .../0.9/images/anchor-copy-button.svg | 4 + .../previousDocVersions/0.9/images/arrow_down.svg | 3 + .../previousDocVersions/0.9/images/copy-icon.svg | 3 + .../0.9/images/copy-successful-icon.svg | 3 + .../0.9/images/footer-go-to-link.svg | 3 + .../0.9/images/go-to-top-icon.svg | 4 + .../previousDocVersions/0.9/images/logo-icon.svg | 10 + .../0.9/images/nav-icons/abstract-class-kotlin.svg | 22 + .../0.9/images/nav-icons/abstract-class.svg | 20 + .../0.9/images/nav-icons/annotation-kotlin.svg | 9 + .../0.9/images/nav-icons/annotation.svg | 7 + .../0.9/images/nav-icons/class-kotlin.svg | 9 + .../0.9/images/nav-icons/class.svg | 7 + .../0.9/images/nav-icons/enum-kotlin.svg | 9 + .../0.9/images/nav-icons/enum.svg | 7 + .../0.9/images/nav-icons/exception-class.svg | 7 + .../0.9/images/nav-icons/field-value.svg | 6 + .../0.9/images/nav-icons/field-variable.svg | 6 + .../0.9/images/nav-icons/function.svg | 7 + .../0.9/images/nav-icons/interface-kotlin.svg | 9 + .../0.9/images/nav-icons/interface.svg | 7 + .../0.9/images/nav-icons/object.svg | 9 + .../0.9/images/theme-toggle.svg | 4 + .../previousDocVersions/0.9/index.html | 92 ++ .../previousDocVersions/0.9/navigation.html | 32 + .../previousDocVersions/0.9/not-found-version.html | 189 +++ .../previousDocVersions/0.9/package-list | 7 + .../previousDocVersions/0.9/scripts/clipboard.js | 52 + .../previousDocVersions/0.9/scripts/main.js | 44 + .../0.9/scripts/navigation-loader.js | 91 ++ .../previousDocVersions/0.9/scripts/pages.json | 1 + .../0.9/scripts/platform-content-handler.js | 359 ++++++ .../previousDocVersions/0.9/scripts/prism.js | 22 + .../0.9/scripts/sourceset_dependencies.js | 1 + .../scripts/symbol-parameters-wrapper_deferred.js | 83 ++ .../0.9/styles/jetbrains-mono.css | 17 + .../previousDocVersions/0.9/styles/logo-styles.css | 15 + .../previousDocVersions/0.9/styles/main.css | 118 ++ .../previousDocVersions/0.9/styles/multimodule.css | 55 + .../previousDocVersions/0.9/styles/prism.css | 213 ++++ .../previousDocVersions/0.9/styles/style.css | 1293 ++++++++++++++++++++ .../previousDocVersions/0.9/version.json | 1 + examples/maven/README.md | 11 + examples/maven/pom.xml | 3 + examples/plugin/hide-internal-api/README.md | 19 +- .../plugin-development/sample-plugin-tutorial.md | 5 + plugins/README.md | 14 + plugins/all-modules-page/README.md | 7 + plugins/android-documentation/README.md | 10 + plugins/base/README.md | 21 + plugins/gfm/README.md | 17 + plugins/javadoc/README.md | 19 + plugins/jekyll/README.md | 17 + plugins/kotlin-as-java/README.md | 15 + plugins/mathjax/README.md | 27 + plugins/templating/README.md | 4 + plugins/versioning/README.md | 332 +++++ plugins/versioning/versioning-plugin-example.png | Bin 0 -> 43684 bytes 138 files changed, 4691 insertions(+), 282 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/gradle/README.md create mode 100644 examples/gradle/dokka-customFormat-example/demo.png create mode 100644 examples/gradle/dokka-gradle-example/README.md create mode 100644 examples/gradle/dokka-gradle-example/demo.png create mode 100644 examples/gradle/dokka-kotlinAsJava-example/README.md create mode 100644 examples/gradle/dokka-kotlinAsJava-example/demo.png create mode 100644 examples/gradle/dokka-library-publishing-example/README.md create mode 100644 examples/gradle/dokka-multimodule-example/README.md create mode 100644 examples/gradle/dokka-multimodule-example/demo.png create mode 100644 examples/gradle/dokka-multimodule-example/gradle.properties delete mode 100644 examples/gradle/dokka-multimodule-example/parentProject/childProjectA/Module.md create mode 100644 examples/gradle/dokka-multimodule-example/parentProject/childProjectA/ModuleA.md delete mode 100644 examples/gradle/dokka-multimodule-example/parentProject/childProjectB/Module.md create mode 100644 examples/gradle/dokka-multimodule-example/parentProject/childProjectB/ModuleB.md create mode 100644 examples/gradle/dokka-multiplatform-example/README.md create mode 100644 examples/gradle/dokka-multiplatform-example/demo.png delete mode 100644 examples/gradle/dokka-multiplatform-example/gradle.properties delete mode 100644 examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org.kotlintestmpp.common/main.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/coroutines.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/getCurrentDate.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/customJdk9/kotlin/demo/CustomSourceSetFile.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/asyncWithDealy.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/main.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/shouldbesuppressed/supp.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java create mode 100644 examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/MainCommand.java delete mode 100644 examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/asyncWithDealy.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/main.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/shouldbesuppressed/supp.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/linuxMain/kotlin/org/kotlintestmpp/CInterop.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/linuxMain/kotlin/org/kotlintestmpp/LinuxCoroutineExtensions.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/linuxMain/kotlin/org/kotlintestmpp/LinuxDateUtils.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/linuxMain/kotlin/org/kotlintestmpp/asyncWithDealy.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/linuxMain/kotlin/org/kotlintestmpp/cinterop.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/linuxMain/kotlin/org/kotlintestmpp/getCurrentDate.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/macosMain/kotlin/org/kotlintestmpp/MacOsCoroutineExtensions.kt create mode 100644 examples/gradle/dokka-multiplatform-example/src/macosMain/kotlin/org/kotlintestmpp/MacOsDateUtils.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/macosMain/kotlin/org/kotlintestmpp/asyncWithDealy.kt delete mode 100644 examples/gradle/dokka-multiplatform-example/src/macosMain/kotlin/org/kotlintestmpp/getCurrentDate.kt create mode 100644 examples/gradle/dokka-versioning-multimodule-example/README.md create mode 100644 examples/gradle/dokka-versioning-multimodule-example/demo.png create mode 100644 examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/src/main/kotlin/demo/FancyAPI.kt create mode 100644 examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectB/src/main/kotlin/demo/Functions.kt create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/-child-project-a-class/-child-project-a-class.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/-child-project-a-class/index.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/demo/index.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/index.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectA/navigation.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectB/demo/-child-project-b-class/-child-project-b-class.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectB/demo/-child-project-b-class/index.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectB/demo/index.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectB/index.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/childProjectB/navigation.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/anchor-copy-button.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/arrow_down.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/copy-icon.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/copy-successful-icon.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/footer-go-to-link.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/go-to-top-icon.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/logo-icon.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/abstract-class-kotlin.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/abstract-class.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/annotation-kotlin.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/annotation.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/class-kotlin.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/class.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/enum-kotlin.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/enum.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/exception-class.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/field-value.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/field-variable.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/function.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/interface-kotlin.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/interface.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/nav-icons/object.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/images/theme-toggle.svg create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/index.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/navigation.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/not-found-version.html create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/package-list create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/scripts/clipboard.js create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/scripts/main.js create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/scripts/navigation-loader.js create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/scripts/pages.json create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/scripts/platform-content-handler.js create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/scripts/prism.js create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/scripts/sourceset_dependencies.js create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/scripts/symbol-parameters-wrapper_deferred.js create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/styles/jetbrains-mono.css create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/styles/logo-styles.css create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/styles/main.css create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/styles/multimodule.css create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/styles/prism.css create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/styles/style.css create mode 100644 examples/gradle/dokka-versioning-multimodule-example/previousDocVersions/0.9/version.json create mode 100644 examples/maven/README.md create mode 100644 plugins/README.md create mode 100644 plugins/all-modules-page/README.md create mode 100644 plugins/android-documentation/README.md create mode 100644 plugins/base/README.md create mode 100644 plugins/gfm/README.md create mode 100644 plugins/javadoc/README.md create mode 100644 plugins/jekyll/README.md create mode 100644 plugins/kotlin-as-java/README.md create mode 100644 plugins/mathjax/README.md create mode 100644 plugins/templating/README.md create mode 100644 plugins/versioning/README.md create mode 100644 plugins/versioning/versioning-plugin-example.png diff --git a/.github/workflows/dokka-examples.yml b/.github/workflows/dokka-examples.yml index 1e99f499..f1167771 100644 --- a/.github/workflows/dokka-examples.yml +++ b/.github/workflows/dokka-examples.yml @@ -90,8 +90,6 @@ jobs: strategy: matrix: include: - - task: "dokkaCustomFormat" - dir: "examples/gradle/dokka-customFormat-example" - task: "dokkaHtmlMultiModule" dir: "examples/gradle/dokka-multimodule-example" steps: diff --git a/.github/workflows/gh-pages-examples.yml b/.github/workflows/gh-pages-examples.yml index b5f3f13b..38d1a416 100644 --- a/.github/workflows/gh-pages-examples.yml +++ b/.github/workflows/gh-pages-examples.yml @@ -48,7 +48,10 @@ jobs: if: github.repository == 'Kotlin/dokka' strategy: matrix: - projects: [ dokka-versioning-multimodule-example ] + projects: [ + dokka-versioning-multimodule-example, + dokka-multimodule-example + ] steps: - uses: actions/checkout@v3 - uses: dorny/paths-filter@v2 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ca58ff4d..a19a9529 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,41 +1,89 @@ -## 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. - -Here's how to import and configure Dokka in IntelliJ IDEA: - * Select "Open" from the IDEA welcome screen, or File > Open if a project is - already open -* Select the directory with your clone of Dokka - * Note: IDEA may have an error after the project is initally opened; it is OK - to ignore this as the next step will address this error -* After IDEA opens the project, select File > New > Module from existing sources - and select the `build.gradle` file from the root directory of your Dokka clone -* Use the default options and select "OK" -* After Dokka is loaded into IDEA, open the Gradle tool window (View > Tool - Windows > Gradle) and click on the top left "Refresh all Gradle projects" - button -* Verify the following project settings. In File > Settings > Build, Execution, - Deployment > Build Tools > Gradle > Runner: - * Ensure "Delegate IDE build/run actions to gradle" is checked - * "Gradle Test Runner" should be selected in the "Run tests using" drop-down - menu -* Note: After closing and re-opening the project, IDEA may give an error - message: "Error Loading Project: Cannot load 3 modules". Open up the details - of the error, and click "Remove Selected", as these module `.iml` files are - safe to remove. - -## Using/testing locally built Dokka - -If you want to use/test your locally built Dokka in a project, do the following: +# Contributing Guidelines + +There are three main ways you can contribute to Dokka's development: + +* Submitting issues. +* Submitting fixes/changes/improvements via pull requests. +* Developing community plugins. + +## Submitting issues + +Bug reports, feature requests and questions are welcome. Submit issues [here](https://github.com/Kotlin/dokka/issues). + +* Search for existing issues to avoid reporting duplicates. +* When submitting a bug report: + * Test it against the most recently released version. It might have been fixed already. + * Include code that reproduces the problem. Provide a complete reproducer, yet minimize it as much as + possible. A separate project that can be cloned is ideal. + * If the bug is in behavior, explain what behavior you expected and what the actual result is. +* When submitting a feature request: + * Explain why you need the feature. + * Explaining the problem you face is more important than suggesting a solution. + Report your problem even if you have no proposed solution. + +## Submitting PRs + +Dokka has extensive [Developer Guides](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/) documentation +which goes over the development [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) and +[Dokka's architecture](https://kotlin.github.io/dokka/1.7.20/developer_guide/architecture/architecture_overview/), +which can help you understand how to achieve what you want and where to look. + +All development (both new features and bugfixes) takes place in the `master` branch, it contains sources for the next +version of Dokka. + +For any code changes: + +* Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). + Use 4 spaces for indentation. +* [Build the project](#building) to make sure it all works and tests pass. +* Write tests that reproduce the bug or test new features. +* PRs without tests are accepted only in exceptional circumstances if it is evident that writing the + corresponding test is too hard or otherwise impractical. +* If you add new or change old public API, [update public API dump](#updating-public-api-dump), otherwise it will fail + the build. + +Please [contact maintainers](#contacting-maintainers) in advance to coordinate any big piece of work. + +### Building + +Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run integration +tests as well, which might take some time and will consume a lot of RAM (~20-30 GB), so you would usually want to exclude +integration tests when building locally: + +```Bash +./gradlew build -x integrationTest +``` + +Unit tests which are run as part of `build` should not take much time, but you can also skip it with `-x test`. + +### Using/testing locally built Dokka + +Below you will find a bare-bones instruction on how to use and test locally built Dokka. For more details and examples, +visit [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) topic. + 1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version. - For example, you can set it to something like `1.7.20-my-fix-SNAPSHOT`. -2. Publish it to maven local (`./gradlew publishToMavenLocal`) -3. In the project you want to generate documentation for, add maven local as a plugin/dependency + For instance, you can set it to something like `1.7.20-my-fix-SNAPSHOT`. +2. Publish it to Maven Local (`./gradlew publishToMavenLocal`) +3. In the project for which you want to generate documentation add Maven Local as a buildscript/dependency repository (`mavenLocal()`) -4. Update your dokka dependency to the version you've just published: +4. Update your Dokka dependency to the version you've just published: + ```kotlin plugins { id("org.jetbrains.dokka") version "1.7.20-my-fix-SNAPSHOT" } ``` + +### Updating public API dump + +[Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) +is used to keep track of public API changes. + +Run `./gradlew apiDump` to update API index files after introducing new or changing old public API. Commit updated +API indexes together with other changes. + +## Contacting maintainers + +* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues). +* Discussions and general inquiries — use `#dokka` channel in + [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..5f78cb6b --- /dev/null +++ b/examples/README.md @@ -0,0 +1,25 @@ +# Dokka examples + +## Gradle + +| Project | Description | +|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [dokka-customFormat-example](gradle/dokka-customFormat-example) | Demonstrates how to override `.css` styles and add custom images as assets, allowing you to change the logo used in the header. | +| [dokka-gradle-example](gradle/dokka-gradle-example) | Demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it. | +| [dokka-kotlinAsJava-example](gradle/dokka-kotlinAsJava-example) | Demonstrates how to apply Dokka plugins, [Kotlin as Java](../plugins/kotlin-as-java) specifically. | +| [dokka-library-publishing-example](gradle/dokka-library-publishing-example) | Demonstrates how to integrate Dokka into the publishing process of a library, adding documentation generated by Dokka as artifacts. | +| [dokka-multimodule-example](gradle/dokka-multimodule-example) | Demonstrates how to apply and configure Dokka in a [multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html). | +| [dokka-multiplatform-example](gradle/dokka-multiplatform-example) | Demonstrates Dokka's configuration and output for a simple [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project. | +| [dokka-versioning-multimodule-example](gradle/dokka-versioning-multimodule-example) | Demonstrates configuration of Dokka's [versioning plugin](../../../plugins/versioning), which allows readers to navigate through different versions of documentation. | + +## Maven + +| Project | Description | +|----------------|-----------------------------------------------------| +| [maven](maven) | Simple Maven project with basic Dokka configuration | + +## Plugins + +| Project | Description | +|-----------------------------------------------|--------------------------------------------------------------------------------------------------------| +| [hide-internal-api](plugin/hide-internal-api) | Dokka plugin that excludes declarations from generated documentation based on an `Internal` annotation | diff --git a/examples/gradle/README.md b/examples/gradle/README.md new file mode 100644 index 00000000..ec3b4e95 --- /dev/null +++ b/examples/gradle/README.md @@ -0,0 +1,11 @@ +# Gradle examples + +| Project | Description | +|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [dokka-customFormat-example](gradle/dokka-customFormat-example) | Demonstrates how to override `.css` styles and add custom images as assets, allowing you to change the logo used in the header. | +| [dokka-gradle-example](gradle/dokka-gradle-example) | Demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it. | +| [dokka-kotlinAsJava-example](gradle/dokka-kotlinAsJava-example) | Demonstrates how to apply Dokka plugins, [Kotlin as Java](../plugins/kotlin-as-java) specifically. | +| [dokka-library-publishing-example](gradle/dokka-library-publishing-example) | Demonstrates how to integrate Dokka into the publishing process of a library, adding documentation generated by Dokka as artifacts. | +| [dokka-multimodule-example](gradle/dokka-multimodule-example) | Demonstrates how to apply and configure Dokka in a [multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html). | +| [dokka-multiplatform-example](gradle/dokka-multiplatform-example) | Demonstrates Dokka's configuration and output for a simple [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project. | +| [dokka-versioning-multimodule-example](gradle/dokka-versioning-multimodule-example) | Demonstrates configuration of Dokka's [versioning plugin](../../../plugins/versioning), which allows readers to navigate through different versions of documentation. | diff --git a/examples/gradle/dokka-customFormat-example/README.md b/examples/gradle/dokka-customFormat-example/README.md index 00dd668c..a25cd80e 100644 --- a/examples/gradle/dokka-customFormat-example/README.md +++ b/examples/gradle/dokka-customFormat-example/README.md @@ -1,24 +1,17 @@ ## Dokka custom format example -This example demonstrates a few things: +This example demonstrates how to override `.css` styles and add custom images as assets, allowing +you to change the logo used in the header. -1. How to override css styles and add custom images. -2. How to change logo used in the header. -3. How to register a custom `Dokka` task with its own independent configuration. +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-customFormat-example/html/index.html). -### Running +![screenshot demonstration of output](demo.png) -`dokkaCustomFormat` task has been created in the buildscript of this example project with a few configuration changes. +### Running -In order to see the full effect of these changes, run `dokkaCustomFormat` task from your IDE or execute -the following command: +Run `dokkaHtml` task to generate documentation with the custom logo in place: ```bash -./gradlew clean dokkaCustomFormat +./gradlew dokkaHtml ``` - ---- - -If you run any other `Dokka` task, such as `dokkaHtml`, you'll see vanilla `Dokka` without any alterations. -This is because changes to configuration are applied only within `dokkaCustomFormat` task. This can be useful -if you want to generate multiple versions of documentation with different configuration settings. diff --git a/examples/gradle/dokka-customFormat-example/build.gradle.kts b/examples/gradle/dokka-customFormat-example/build.gradle.kts index 8d1d36ce..0c845572 100644 --- a/examples/gradle/dokka-customFormat-example/build.gradle.kts +++ b/examples/gradle/dokka-customFormat-example/build.gradle.kts @@ -1,4 +1,6 @@ import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.DokkaBaseConfiguration plugins { kotlin("jvm") version "1.7.20" @@ -15,16 +17,16 @@ repositories { mavenCentral() } -/** - * Custom format adds a custom logo - */ -tasks.register("dokkaCustomFormat") { - pluginConfiguration { +tasks.dokkaHtml { + pluginConfiguration { // Dokka's stylesheets and assets with conflicting names will be overriden. // In this particular case, logo-styles.css will be overriden and ktor-logo.png will // be added as an additional image asset customStyleSheets = listOf(file("logo-styles.css")) customAssets = listOf(file("ktor-logo.png")) + + // Text used in the footer + footerMessage = "(c) Custom Format Dokka example" } } diff --git a/examples/gradle/dokka-customFormat-example/demo.png b/examples/gradle/dokka-customFormat-example/demo.png new file mode 100644 index 00000000..8f9b88b0 Binary files /dev/null and b/examples/gradle/dokka-customFormat-example/demo.png differ diff --git a/examples/gradle/dokka-gradle-example/README.md b/examples/gradle/dokka-gradle-example/README.md new file mode 100644 index 00000000..3401e8e9 --- /dev/null +++ b/examples/gradle/dokka-gradle-example/README.md @@ -0,0 +1,22 @@ +# Dokka Gradle example + +This example demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it. + +Configuration changes: + +* Custom project name used in the header, `Dokka Gradle Example`. +* Description for the project and the packages taken from [Module.md](Module.md). +* Documentation contains source links that lead to declarations in this GitHub repository. + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-gradle-example/html/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtml` task to generate documentation for this example: + +```bash +./gradlew dokkaHtml +``` diff --git a/examples/gradle/dokka-gradle-example/build.gradle.kts b/examples/gradle/dokka-gradle-example/build.gradle.kts index ac62fccd..db3d91b9 100644 --- a/examples/gradle/dokka-gradle-example/build.gradle.kts +++ b/examples/gradle/dokka-gradle-example/build.gradle.kts @@ -18,8 +18,14 @@ dependencies { tasks.withType().configureEach { dokkaSourceSets { named("main") { + // used as project name in the header moduleName.set("Dokka Gradle Example") + + // contains descriptions for the module and the packages includes.from("Module.md") + + // adds source links that lead to this repository, allowing readers + // to easily find source code for inspected declarations sourceLink { localDirectory.set(file("src/main/kotlin")) remoteUrl.set(URL("https://github.com/Kotlin/dokka/tree/master/" + diff --git a/examples/gradle/dokka-gradle-example/demo.png b/examples/gradle/dokka-gradle-example/demo.png new file mode 100644 index 00000000..4462f3b5 Binary files /dev/null and b/examples/gradle/dokka-gradle-example/demo.png differ diff --git a/examples/gradle/dokka-kotlinAsJava-example/README.md b/examples/gradle/dokka-kotlinAsJava-example/README.md new file mode 100644 index 00000000..647b0e6d --- /dev/null +++ b/examples/gradle/dokka-kotlinAsJava-example/README.md @@ -0,0 +1,19 @@ +# Dokka Kotlin-as-Java plugin example + +This example demonstrates how you can apply a Dokka plugin in a simple Gradle project. + +In particular, it applies [Kotlin as Java](../../../plugins/kotlin-as-java) Dokka plugin that renders all +Kotlin signatures as Java signatures. + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-kotlinAsJava-example/html/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtml` task to generate documentation for this example: + +```bash +./gradlew dokkaHtml +``` diff --git a/examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts b/examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts index 8150fdd1..d45be539 100644 --- a/examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts +++ b/examples/gradle/dokka-kotlinAsJava-example/build.gradle.kts @@ -11,7 +11,7 @@ dependencies { implementation(kotlin("stdlib")) testImplementation(kotlin("test-junit")) - // Will apply the plugin to all dokka tasks + // Will apply the plugin to all Dokka tasks dokkaPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20") // Will apply the plugin only to the `:dokkaHtml` task diff --git a/examples/gradle/dokka-kotlinAsJava-example/demo.png b/examples/gradle/dokka-kotlinAsJava-example/demo.png new file mode 100644 index 00000000..92f1170f Binary files /dev/null and b/examples/gradle/dokka-kotlinAsJava-example/demo.png differ diff --git a/examples/gradle/dokka-library-publishing-example/README.md b/examples/gradle/dokka-library-publishing-example/README.md new file mode 100644 index 00000000..60d967b8 --- /dev/null +++ b/examples/gradle/dokka-library-publishing-example/README.md @@ -0,0 +1,41 @@ +# Dokka Library publishing example + +This example demonstrates how you can integrate Dokka into the publishing process of your library, adding +documentation generated by Dokka as artifacts. + +This is useful because some repositories, like Maven Central, require documentation (`javadoc.jar`) to be published +alongside library artifacts. + +You can also use services like [javadoc.io](https://javadoc.io/) to host of your library's API documentation for free +and without any additional setup - it will take documentation pages straight from the published artifact. It works with +both HTML and Javadoc formats as demonstrated by +[com.trib3's Javadocs](https://javadoc.io/doc/com.trib3/server/latest/index.html). + +## Running + +Run `dokkaHtml` task to generate documentation for this example: + +```bash +./gradlew dokkaHtml +``` + +### Javadoc jar + +Run `dokkaJavadocJar` task to create a jar file that contains documentation generated in Dokka's Javadoc format. + +```Bash +./gradlew dokkaJavadocJar +``` + +After that, you can find the jar under `build/libs/dokka-library-publishing-example-javadoc.jar` + +### HTML jar + + +Run `dokkaHtmlJar` task to create a jar file that contains documentation generated in Dokka's HTML format. + +```Bash +./gradlew dokkaHtmlJar +``` + +After that, you can find the jar under `build/libs/dokka-library-publishing-example-html.jar` diff --git a/examples/gradle/dokka-multimodule-example/README.md b/examples/gradle/dokka-multimodule-example/README.md new file mode 100644 index 00000000..c8b224ec --- /dev/null +++ b/examples/gradle/dokka-multimodule-example/README.md @@ -0,0 +1,25 @@ +# Dokka MultiModule example + +This example demonstrates how to apply and configure Dokka in a +[multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html). + +You can also learn how to set Dokka's version in [gradle.properties](gradle.properties) using `pluginManagement` +configuration block in [settings.gradle.kts](settings.gradle.kts). + +____ + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-multimodule-example/htmlMultiModule/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtmlMultiModule` task to generate documentation for this example: + +```bash +./gradlew dokkaHtmlMultiModule +``` + +It will generate complete documentation for the root project and its subprojects, with a common +Table of Contents. diff --git a/examples/gradle/dokka-multimodule-example/demo.png b/examples/gradle/dokka-multimodule-example/demo.png new file mode 100644 index 00000000..d25576b8 Binary files /dev/null and b/examples/gradle/dokka-multimodule-example/demo.png differ diff --git a/examples/gradle/dokka-multimodule-example/gradle.properties b/examples/gradle/dokka-multimodule-example/gradle.properties new file mode 100644 index 00000000..664b5f0e --- /dev/null +++ b/examples/gradle/dokka-multimodule-example/gradle.properties @@ -0,0 +1,2 @@ +kotlinVersion=1.7.20 +dokkaVersion=1.7.20 diff --git a/examples/gradle/dokka-multimodule-example/parentProject/build.gradle.kts b/examples/gradle/dokka-multimodule-example/parentProject/build.gradle.kts index 397ad22f..66b32b18 100644 --- a/examples/gradle/dokka-multimodule-example/parentProject/build.gradle.kts +++ b/examples/gradle/dokka-multimodule-example/parentProject/build.gradle.kts @@ -1,19 +1,32 @@ +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.gradle.DokkaTaskPartial + plugins { - /** - * Kotlin plugin necessary because of potential Gradle bug! - * This is not necessary if the kotlin gradle plugin is added as buildscript - * dependency like - * - * buildscript { - * dependencies { - * classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") - * } - * } - */ kotlin("jvm") id("org.jetbrains.dokka") } +// You can apply and configure Dokka in each subproject +// individially or configure all subprojects at once +subprojects { + apply(plugin = "org.jetbrains.dokka") + + tasks.withType().configureEach { + dokkaSourceSets.configureEach { + documentedVisibilities.set(setOf( + Visibility.PUBLIC, + Visibility.PROTECTED + )) + } + } +} + +// Configures only the parent MultiModule task, +// this will not affect subprojects +tasks.dokkaHtmlMultiModule { + moduleName.set("Dokka MultiModule Example") +} + dependencies { implementation(kotlin("stdlib")) } diff --git a/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/Module.md b/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/Module.md deleted file mode 100644 index e6cf0e04..00000000 --- a/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/Module.md +++ /dev/null @@ -1,5 +0,0 @@ -# Module childProjectA -This is the child module a - -# Package demo -This package contains a few examples of Dokka usage. diff --git a/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/ModuleA.md b/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/ModuleA.md new file mode 100644 index 00000000..12712d97 --- /dev/null +++ b/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/ModuleA.md @@ -0,0 +1,5 @@ +# Module childProjectA +This is the child module A + +# Package demo +This package contains a few examples of Dokka usage. diff --git a/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/build.gradle.kts b/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/build.gradle.kts index b3c42aba..e13819a1 100644 --- a/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/build.gradle.kts +++ b/examples/gradle/dokka-multimodule-example/parentProject/childProjectA/build.gradle.kts @@ -9,10 +9,12 @@ dependencies { implementation(kotlin("stdlib")) } +// configuration specific to this subproject. +// notice the use of Partial task tasks.withType().configureEach { dokkaSourceSets { configureEach { - includes.from("Module.md") + includes.from("ModuleA.md") } } } diff --git a/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/Module.md b/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/Module.md deleted file mode 100644 index 27031edf..00000000 --- a/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/Module.md +++ /dev/null @@ -1,5 +0,0 @@ -# Module childProjectB -This is the child module b - -# Package demo -This package contains a few examples of Dokka usage. diff --git a/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/ModuleB.md b/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/ModuleB.md new file mode 100644 index 00000000..18a92a33 --- /dev/null +++ b/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/ModuleB.md @@ -0,0 +1,5 @@ +# Module childProjectB +This is the child module B + +# Package demo +This package contains a few examples of Dokka usage. diff --git a/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/build.gradle.kts b/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/build.gradle.kts index b3c42aba..089813a8 100644 --- a/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/build.gradle.kts +++ b/examples/gradle/dokka-multimodule-example/parentProject/childProjectB/build.gradle.kts @@ -9,10 +9,12 @@ dependencies { implementation(kotlin("stdlib")) } +// configuration specific to this subproject. +// notice the use of Partial task tasks.withType().configureEach { dokkaSourceSets { configureEach { - includes.from("Module.md") + includes.from("ModuleB.md") } } } diff --git a/examples/gradle/dokka-multimodule-example/settings.gradle.kts b/examples/gradle/dokka-multimodule-example/settings.gradle.kts index ef724ba5..9844b3cc 100644 --- a/examples/gradle/dokka-multimodule-example/settings.gradle.kts +++ b/examples/gradle/dokka-multimodule-example/settings.gradle.kts @@ -1,7 +1,10 @@ pluginManagement { + val kotlinVersion: String by settings + val dokkaVersion: String by settings + plugins { - kotlin("jvm") version "1.7.20" - id("org.jetbrains.dokka") version ("1.7.20") + kotlin("jvm") version kotlinVersion + id("org.jetbrains.dokka") version dokkaVersion } } diff --git a/examples/gradle/dokka-multiplatform-example/README.md b/examples/gradle/dokka-multiplatform-example/README.md new file mode 100644 index 00000000..9b8a85e6 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/README.md @@ -0,0 +1,29 @@ +# Dokka Multiplatform example + +This example demonstrates Dokka's configuration and output for a simple +[Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project. + +It contains [Kotlin source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) for different +platforms that are automatically picked up by Dokka from the Kotlin Gradle Plugin, and an additional custom source +set known to Dokka only. + +The example demonstrates the following things: + +* Documentation for common code +* Documentation for expect/actual declarations available via tabs +* Documentation for platform-specific declarations, including functions from different source sets, but + with clashing names +* Use of Platform-specific API, such as `CPointer` from `kotlinx.cinterop` + +You can see up-to-date documentation generated for this example on +[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-multiplatform-example/html/index.html). + +![screenshot demonstration of output](demo.png) + +### Running + +Run `dokkaHtml` task in order to generate documentation for this example: + +```bash +./gradlew dokkaHtml +``` diff --git a/examples/gradle/dokka-multiplatform-example/build.gradle.kts b/examples/gradle/dokka-multiplatform-example/build.gradle.kts index c444bba0..64b5a003 100644 --- a/examples/gradle/dokka-multiplatform-example/build.gradle.kts +++ b/examples/gradle/dokka-multiplatform-example/build.gradle.kts @@ -12,11 +12,11 @@ repositories { mavenCentral() } -group = "org.test" +group = "org.dokka.example" version = "1.0-SNAPSHOT" kotlin { - jvm() // Create a JVM target with the default name "jvm" + jvm() // Creates a JVM target with the default name "jvm" linuxX64("linux") macosX64("macos") js() @@ -32,9 +32,7 @@ kotlin { tasks.withType().configureEach { dokkaSourceSets { - /* - Create custom source set (not known to the Kotlin Gradle Plugin) - */ + // Create a custom source set not known to the Kotlin Gradle Plugin register("customSourceSet") { this.jdkVersion.set(9) this.displayName.set("custom") diff --git a/examples/gradle/dokka-multiplatform-example/demo.png b/examples/gradle/dokka-multiplatform-example/demo.png new file mode 100644 index 00000000..58798ccf Binary files /dev/null and b/examples/gradle/dokka-multiplatform-example/demo.png differ diff --git a/examples/gradle/dokka-multiplatform-example/gradle.properties b/examples/gradle/dokka-multiplatform-example/gradle.properties deleted file mode 100644 index 29e08e8c..00000000 --- a/examples/gradle/dokka-multiplatform-example/gradle.properties +++ /dev/null @@ -1 +0,0 @@ -kotlin.code.style=official \ No newline at end of file diff --git a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org.kotlintestmpp.common/main.kt b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org.kotlintestmpp.common/main.kt deleted file mode 100644 index 1746d513..00000000 --- a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org.kotlintestmpp.common/main.kt +++ /dev/null @@ -1,4 +0,0 @@ -package org.kotlintestmpp.common - -class Foo {} - diff --git a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt new file mode 100644 index 00000000..30bea657 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/CommonCoroutineExtensions.kt @@ -0,0 +1,15 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.CoroutineDispatcher +import kotlinx.coroutines.Deferred + +/** + * Common `expect` declaration + */ +expect fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred + +/** + * Common coroutine extension + */ +fun CoroutineDispatcher.name(): String = TODO("Not implemented") diff --git a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt new file mode 100644 index 00000000..b241f5ea --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/CommonDateUtils.kt @@ -0,0 +1,14 @@ +package org.kotlintestmpp.date + +/** + * Common `expect` declaration + */ +expect fun getCurrentDate(): String + +/** + * Common date util function + */ +fun getDate(): String { + return "Today's Date is ${getCurrentDate()}" +} + diff --git a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt new file mode 100644 index 00000000..96c825c5 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/common/Foo.kt @@ -0,0 +1,7 @@ +package org.kotlintestmpp.common + +/** + * Common Foo class + */ +class Foo {} + diff --git a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/coroutines.kt b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/coroutines.kt deleted file mode 100644 index 330cd83a..00000000 --- a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/coroutines.kt +++ /dev/null @@ -1,6 +0,0 @@ -package org.kotlintestmpp - -import kotlinx.coroutines.CoroutineScope -import kotlinx.coroutines.Deferred - -expect fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred diff --git a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/getCurrentDate.kt b/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/getCurrentDate.kt deleted file mode 100644 index 46a1dd23..00000000 --- a/examples/gradle/dokka-multiplatform-example/src/commonMain/kotlin/org/kotlintestmpp/getCurrentDate.kt +++ /dev/null @@ -1,8 +0,0 @@ -package org.kotlintestmpp - -expect fun getCurrentDate(): String - -fun getDate(): String { - return "Today's Date is ${getCurrentDate()}" -} - diff --git a/examples/gradle/dokka-multiplatform-example/src/customJdk9/kotlin/demo/CustomSourceSetFile.kt b/examples/gradle/dokka-multiplatform-example/src/customJdk9/kotlin/demo/CustomSourceSetFile.kt deleted file mode 100644 index 5b642416..00000000 --- a/examples/gradle/dokka-multiplatform-example/src/customJdk9/kotlin/demo/CustomSourceSetFile.kt +++ /dev/null @@ -1,11 +0,0 @@ -package demo - -/** - * This class demonstrates custom dokka source sets - */ -class CustomSourceSetFile { - /** - * This function will not do anything - */ - fun thisIsAFunction() {} -} diff --git a/examples/gradle/dokka-multiplatform-example/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt b/examples/gradle/dokka-multiplatform-example/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt new file mode 100644 index 00000000..d77b959b --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/customJdk9/kotlin/org/kotlintest/jdk9/CustomSourceSetFile.kt @@ -0,0 +1,11 @@ +package org.kotlintest.jdk9 + +/** + * This class demonstrates custom dokka source sets + */ +class CustomSourceSetFile { + /** + * This function will not do anything + */ + fun thisIsAFunction() {} +} diff --git a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt new file mode 100644 index 00000000..85d6beb0 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * JS actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt new file mode 100644 index 00000000..2f4f3c45 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * JS actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + return "test" +} diff --git a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt new file mode 100644 index 00000000..76757359 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/JsFunctions.kt @@ -0,0 +1,18 @@ +package org.kotlintestmpp + +/** + * Function declares in JS source set + */ +fun js() {} + +/** + * Function declared in JS source set. + * + * Function with the same name exists in another source set as well. + */ +fun shared() {} + +/** + * Extension declared in JS source set + */ +fun String.myExtension() = println("test") diff --git a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/asyncWithDealy.kt b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/asyncWithDealy.kt deleted file mode 100644 index 7b5fe652..00000000 --- a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/asyncWithDealy.kt +++ /dev/null @@ -1,8 +0,0 @@ -package org.kotlintestmpp - -import kotlinx.coroutines.CoroutineScope -import kotlinx.coroutines.Deferred - -actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { - TODO("Not yet implemented") -} diff --git a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/main.kt b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/main.kt deleted file mode 100644 index 8cb66e6d..00000000 --- a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/org/kotlintestmpp/main.kt +++ /dev/null @@ -1,17 +0,0 @@ -package org.kotlintestmpp - -fun main(args : Array) { - console.log("Hello, world!") -} - -fun js(){} -fun shared(){} - -/** - * Actual function for js - */ -actual fun getCurrentDate(): String { - return "test" -} - -fun String.myExtension() = println("test") \ No newline at end of file diff --git a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/shouldbesuppressed/supp.kt b/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/shouldbesuppressed/supp.kt deleted file mode 100644 index 21dca566..00000000 --- a/examples/gradle/dokka-multiplatform-example/src/jsMain/kotlin/shouldbesuppressed/supp.kt +++ /dev/null @@ -1,11 +0,0 @@ -package shouldbesuppressed - -/** - * This function should not be visible - */ -fun thatShouldNotBeVisible(): String = "oops" - -/** - * This class should not be visible - */ -class DontLookAtMe(val stealth: Int = 9001) \ No newline at end of file diff --git a/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java b/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java new file mode 100644 index 00000000..8b11ca09 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JavaAnnotation.java @@ -0,0 +1,19 @@ +package org.kotlintestmpp; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This is a Java annotation + */ +@Target(ElementType.TYPE) +@Retention(RetentionPolicy.RUNTIME) +public @interface JavaAnnotation { + String usage(); + + String[] aliases(); + + String description(); +} diff --git a/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt b/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt new file mode 100644 index 00000000..8f7fda49 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmCoroutineExtensions.kt @@ -0,0 +1,11 @@ +package org.kotlintestmpp.coroutines + +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred + +/** + * JVM actual implementation for `asyncWithDelay` + */ +actual fun CoroutineScope.asyncWithDealy(delay: Long, block: suspend () -> T): Deferred { + TODO("Not yet implemented") +} diff --git a/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt b/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt new file mode 100644 index 00000000..db7f2d74 --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmDateUtils.kt @@ -0,0 +1,8 @@ +package org.kotlintestmpp.date + +/** + * JVM actual implementation for `getCurrentDate` + */ +actual fun getCurrentDate(): String { + return "test" +} diff --git a/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt b/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt new file mode 100644 index 00000000..0ef8a99d --- /dev/null +++ b/examples/gradle/dokka-multiplatform-example/src/jvmMain/kotlin/org/kotlintestmpp/JvmFunctions.kt @@ -0,0 +1,35 @@ +package org.kotli