Revise README documentation for examples and plugins (#2736)

3 files changed, 20 insertions, 1 deletions

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
--- /dev/null
+++ b/examples/gradle/dokka-kotlinAsJava-example/demo.png