Add documentation to dottydoc API

2 files changed, 63 insertions, 3 deletions

diff --git a/dottydoc/src/dotty/tools/dottydoc/api/java/Dottydoc.java b/dottydoc/src/dotty/tools/dottydoc/api/java/Dottydoc.java
index dbe3f6f41..1bdfe0488 100644
--- a/dottydoc/src/dotty/tools/dottydoc/api/java/Dottydoc.java
+++ b/dottydoc/src/dotty/tools/dottydoc/api/java/Dottydoc.java
@@ -7,16 +7,46 @@ import java.util.Map;
 import java.util.List;
 import java.net.URL;
 
-/** FIXME: document me! */
+/**
+ * The Dottydoc API is fairly simple. The tool creates an index by calling:
+ * "createIndex" with the same argument list as you would the compiler - e.g:
+ *
+ * {{{
+ * String[] array = {
+ *     "-language:Scala2"
+ * };
+ *
+ * Map<String, Package> index = createIndex(array);
+ * }}}
+ *
+ * Once the index has been generated, the tool can also build a documentation
+ * API given a Mustache template and a flat resources structure (i.e. absolute
+ * paths to each resource, which will be put in the same directory).
+ *
+ * {{{
+ * buildDocs("path/to/output/dir", templateURL, resources, index);
+ * }}}
+ *
+ * The tool can also generate JSON from the created index using "toJson(index)"
+ * or directly using "createJsonIndex"
+ */
 public class Dottydoc extends DocDriver {
+
+    /** Creates index from compiler arguments */
     public Map<String, Package> createIndex(String[] args) {
         return compiledDocsJava(args);
     }
 
+    /** Creates JSON from compiler arguments */
     public String createJsonIndex(String[] args) {
-        return indexToJson(createIndex(args));
+        return indexToJsonJava(createIndex(args));
+    }
+
+    public String toJson(Map<String, Package> index) {
+        return indexToJsonJava(index);
     }
 
+    /** Creates a documentation from the given parameters */
     public void buildDocs(
         String outputDir,
         URL template,
@@ -26,6 +56,7 @@ public class Dottydoc extends DocDriver {
         new OutputWriter().writeJava(index, outputDir, template, resources);
     }
 
+    /** Writes JSON to an output directory as "index.json" */
     public void writeJson(Map<String, Package> index, String outputDir) {
         new OutputWriter().writeJsonJava(index, outputDir);
     }
diff --git a/dottydoc/src/dotty/tools/dottydoc/api/scala/Dottydoc.scala b/dottydoc/src/dotty/tools/dottydoc/api/scala/Dottydoc.scala
index a2c42d38c..15db81a95 100644
--- a/dottydoc/src/dotty/tools/dottydoc/api/scala/Dottydoc.scala
+++ b/dottydoc/src/dotty/tools/dottydoc/api/scala/Dottydoc.scala
@@ -7,14 +7,43 @@ import dotty.tools.dottydoc.util.OutputWriter
 import scala.collection.Map
 import java.net.URL
 
-/** FIXME: document this class plz */
+/**
+ * The Dottydoc API is fairly simple. The tool creates an index by calling:
+ * "createIndex" with the same argument list as you would the compiler - e.g:
+ *
+ * {{{
+ * val array: Array[String] = Array(
+ *   "-language:Scala2"
+ * )
+ *
+ * val index: Map[String, Package] = createIndex(array)
+ * }}}
+ *
+ * Once the index has been generated, the tool can also build a documentation
+ * API given a Mustache template and a flat resources structure (i.e. absolute
+ * paths to each resource, which will be put in the same directory).
+ *
+ * {{{
+ * buildDocs("path/to/output/dir", templateURL, resources, index)
+ * }}}
+ *
+ * The tool can also generate JSON from the created index using "indexToJson"
+ * or directly using "createJsonIndex"
+ */
 trait Dottydoc extends DocDriver {
+  /** Creates index from compiler arguments */
   def createIndex(args: Array[String]): Map[String, Package] =
     compiledDocs(args)
 
+  /** Creates JSON from compiler arguments */
+  def createJsonIndex(args: Array[String]): String =
+    indexToJson(compiledDocs(args))
+
+  /** Creates a documentation from the given parameters */
   def buildDocs(outDir: String, template: URL, resources: List[URL], index: Map[String, Package]) =
     new OutputWriter().write(index, outDir, template, resources)
 
+  /** Writes JSON to an output directory as "index.json" */
   def writeJson(index: Map[String, Package], outputDir: String) =
     new OutputWriter().writeJson(index, outputDir)
 }