From abf16325cb8909b8c856d2a83ad7c9b05f49130b Mon Sep 17 00:00:00 2001 From: Felix Mulder Date: Mon, 15 Aug 2016 18:22:14 +0200 Subject: Add documentation to dottydoc API --- dottydoc/src/dotty/tools/dottydoc/DottyDoc.scala | 7 +++-- .../dotty/tools/dottydoc/api/java/Dottydoc.java | 35 ++++++++++++++++++++-- .../dotty/tools/dottydoc/api/scala/Dottydoc.scala | 31 ++++++++++++++++++- .../dottydoc/model/comment/CommentParser.scala | 2 +- 4 files changed, 69 insertions(+), 6 deletions(-) (limited to 'dottydoc') diff --git a/dottydoc/src/dotty/tools/dottydoc/DottyDoc.scala b/dottydoc/src/dotty/tools/dottydoc/DottyDoc.scala index e19805d21..a05cd8c25 100644 --- a/dottydoc/src/dotty/tools/dottydoc/DottyDoc.scala +++ b/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) } 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 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 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 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 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) } diff --git a/dottydoc/src/dotty/tools/dottydoc/model/comment/CommentParser.scala b/dottydoc/src/dotty/tools/dottydoc/model/comment/CommentParser.scala index 589e2ebe2..9685b6934 100644 --- a/dottydoc/src/dotty/tools/dottydoc/model/comment/CommentParser.scala +++ b/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") ), -- cgit v1.2.3