Revise README documentation for examples and plugins (#2736)

3 files changed, 28 insertions, 0 deletions

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