Add documentation to dottydoc API

Author: felixmulder

dottydoc/src/dotty/tools/dottydoc/DottyDoc.scala

@@ -70,6 +70,9 @@ abstract class DocDriver extends Driver {
   def compiledDocsJava(args: Array[String]): JMap[String, Package] =
     compiledDocs(args).asJava
 
-  def indexToJson(index: JMap[String, Package]): String =
-    index.asScala.json
+  def indexToJson(index: collection.Map[String, Package]): String =
+    index.json
+
+  def indexToJsonJava(index: JMap[String, Package]): String =
+    indexToJson(index.asScala)
 }

dottydoc/src/dotty/tools/dottydoc/api/java/Dottydoc.java

@@ -7,16 +7,46 @@
 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 void buildDocs(
         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);
     }

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)
 }

dottydoc/src/dotty/tools/dottydoc/model/comment/CommentParser.scala

@@ -347,7 +347,7 @@ trait CommentParser extends util.MemberLookup {
 
     /** listStyle ::= '-' spc | '1.' spc | 'I.' spc | 'i.' spc | 'A.' spc | 'a.' spc
       * Characters used to build lists and their constructors */
-    protected val listStyles = Map[String, (Seq[Block] => Block)]( // TODO Should this be defined at some list companion?
+    protected val listStyles = Map[String, (Seq[Block] => Block)](
       "- "  -> ( UnorderedList(_) ),
       "1. " -> ( OrderedList(_,"decimal") ),
       "I. " -> ( OrderedList(_,"upperRoman") ),