Revise README documentation for examples and plugins (#2736)

1 files changed, 19 insertions, 0 deletions

diff --git a/plugins/javadoc/README.md b/plugins/javadoc/README.md
new file mode 100644
index 00000000..aaa1f272
--- /dev/null
+++ b/plugins/javadoc/README.md
@@ -0,0 +1,19 @@
+# Javadoc plugin
+
+The Javadoc plugin adds a Javadoc output format that looks like Java's Javadoc HTML, but it's for the most part
+a lookalike, so you may experience problems if you try to use it with a tool that expects native
+Javadoc documentation generated by Java.
+
+The Javadoc plugin is shipped with the Dokka Gradle Plugin, so you can start using it right away with one of the following 
+tasks:
+
+* `dokkaJavadoc` - builds Javadoc documentation for single-project builds or for a specific module.
+* `dokkaJavadocCollector` - collects generated Javadoc documentation from submodules and assembles it together.
+
+The Javadoc plugin has its own signature provider that essentially translates Kotlin signatures to Java ones.
+
+To use it with Maven or the CLI runner, you have to add it as a dependency. You can find it on
+[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/javadoc-plugin).
+
+**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to
+[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see.