Merge pull request #11 from lightbend/docs

Add some more usage docs

Author: 2m

README.md

@@ -13,6 +13,28 @@ A [paradox](https://github.com/lightbend/paradox/) directive that automatically
 addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-apidoc" % "<latest>")
 ```
 
+You can now create 'grouped' javadoc/scaladoc references in paradox like:
+
+```
+Look into the documentation for @apidoc[MyClass].
+```
+
+This will automatically find the FQDN of the class when it is unique. When the
+name does not uniquely identify the class, the plugin will check for the
+`scaladsl`/`javadsl` package convention found in Akka projects. If that doesn't
+produce an unambigious result, you will have to use the FQDN.
+
+To limit the packages that are searched for classes, configure the
+`apidocRootPackage` setting:
+
+```
+import com.lightbend.paradox.apidoc.ApidocPlugin.autoImport.apidocRootPackage
+
+(...)
+  apidocRootPackage := "akka",
+(...)
+```
+
 ## License
 
 The license is Apache 2.0, see LICENSE.