Merge pull request #1453 from felixmulder/topic/dottydoc

Add dottydoc

Author: odersky

.gitignore

@@ -1,6 +1,7 @@
 *.DS_Store
 *.class
 *.log
+*.swp
 *~
 *.swp
 
@@ -37,6 +38,7 @@ scala-scala
 
 # Ignore output files but keep the directory
 out/
+build/
 !out/.keep
 
 # Ignore build-file

bridge/src/main/scala/xsbt/ScaladocInterface.scala

@@ -0,0 +1,72 @@
+/* sbt -- Simple Build Tool
+ * Copyright 2008, 2009 Mark Harrah
+ */
+package xsbt
+
+import xsbti.Logger
+import dotty.tools.dottydoc.api.scala.Dottydoc
+import java.net.URL
+
+class ScaladocInterface {
+  def run(args: Array[String], log: Logger, delegate: xsbti.Reporter) =
+    (new DottydocRunner(args, log, delegate)).run()
+}
+
+class DottydocRunner(args: Array[String], log: Logger, delegate: xsbti.Reporter) extends Dottydoc {
+  def run(): Unit = getOutputFolder(args).map { outputFolder =>
+    val index     = createIndex(args)
+    val resources = getResources(args)
+    val template  = getTemplate(resources)
+
+    template.fold(writeJson(index, outputFolder)) { tpl =>
+      buildDocs(outputFolder, tpl, resources, index)
+    }
+  } getOrElse {
+    delegate.log(
+      NoPosition,
+      "No output folder set for API documentation (\"-d\" parameter should be passed to the documentation tool)",
+      xsbti.Severity.Error
+    )
+  }
+
+  private[this] val NoPosition = new xsbti.Position {
+    val line = xsbti.Maybe.nothing[Integer]
+    val lineContent = ""
+    val offset = xsbti.Maybe.nothing[Integer]
+    val sourcePath = xsbti.Maybe.nothing[String]
+    val sourceFile = xsbti.Maybe.nothing[java.io.File]
+    val pointer = xsbti.Maybe.nothing[Integer]
+    val pointerSpace = xsbti.Maybe.nothing[String]
+  }
+
+  private def getStringSetting(name: String): Option[String] =
+    args find (_.startsWith(name)) map (_.drop(name.length))
+
+  private def getOutputFolder(args: Array[String]): Option[String] =
+    args sliding(2) find { case Array(x, _) => x == "-d" } map (_.tail.head.trim)
+
+  private def getTemplate(resources: List[URL]): Option[URL] =
+    resources.find(_.getFile.endsWith("template.html"))
+
+  private def getResources(args: Array[String]): List[URL] = {
+    val cp = args sliding (2) find { case Array(x, _) => x == "-classpath" } map (_.tail.head.trim) getOrElse ""
+
+    cp.split(":").find(_.endsWith("dottydoc-client.jar")).map { resourceJar =>
+      import java.util.jar.JarFile
+      val jarEntries = (new JarFile(resourceJar)).entries
+      var entries: List[URL] = Nil
+
+      while (jarEntries.hasMoreElements) {
+        val entry = jarEntries.nextElement()
+
+        if (!entry.isDirectory()) {
+          val path = s"jar:file:$resourceJar!/${entry.getName}"
+          val url  = new URL(path)
+          entries = url :: entries
+        }
+      }
+
+      entries
+    } getOrElse (Nil)
+  }
+}

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

@@ -0,0 +1,79 @@
+package dotty.tools
+package dottydoc
+
+import core._
+import core.transform._
+import dotc.config.CompilerCommand
+import dotc.config.Printers.dottydoc
+import dotc.core.Contexts._
+import dotc.core.Phases.Phase
+import dotc.typer.FrontEnd
+import dotc.{ CompilationUnit, Compiler, Driver, Run }
+import io.PlainFile
+import model.Package
+import model.json._
+
+import _root_.java.util.{ Map => JMap }
+
+/** Custom Compiler with phases for the documentation tool
+ *
+ *  The idea here is to structure `dottydoc` around the new infrastructure. As
+ *  such, dottydoc will itself be a compiler. It will, however, produce a format
+ *  that can be used by other tools or web-browsers.
+ *
+ *  Example:
+ *    1. Use the existing FrontEnd to typecheck the code being fed to dottydoc
+ *    2. Create an AST that is serializable
+ *    3. Serialize to JS object
+ */
+class DocCompiler extends Compiler {
+  override def phases: List[List[Phase]] = List(
+    List(new DocFrontEnd),
+    List(new DocImplicitsPhase),
+    List(new DocASTPhase),
+    List(DocMiniTransformations(new LinkReturnTypes,
+                                new LinkParamListTypes,
+                                new LinkImplicitlyAddedTypes,
+                                new LinkSuperTypes,
+                                new AlternateConstructors,
+                                new SortMembers))
+  )
+}
+
+class DocFrontEnd extends FrontEnd {
+  override protected def discardAfterTyper(unit: CompilationUnit)(implicit ctx: Context) =
+    unit.isJava
+}
+
+abstract class DocDriver extends Driver {
+  import scala.collection.JavaConverters._
+
+  override def setup(args: Array[String], rootCtx: Context): (List[String], Context) = {
+    val ctx     = rootCtx.fresh
+    val summary = CompilerCommand.distill(args)(ctx)
+
+    ctx.setSettings(summary.sstate)
+    ctx.setSetting(ctx.settings.YkeepComments, true)
+
+    val fileNames = CompilerCommand.checkUsage(summary, sourcesRequired)(ctx)
+    (fileNames, ctx)
+  }
+
+  override def newCompiler(implicit ctx: Context): Compiler = new DocCompiler
+
+  def compiledDocs(args: Array[String]): collection.Map[String, Package] = {
+    val (fileNames, ctx) = setup(args, initCtx.fresh)
+    doCompile(newCompiler(ctx), fileNames)(ctx)
+
+    ctx.docbase.packages[Package]
+  }
+
+  def compiledDocsJava(args: Array[String]): JMap[String, Package] =
+    compiledDocs(args).asJava
+
+  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

@@ -0,0 +1,63 @@
+package dotty.tools.dottydoc.api.java;
+
+import dotty.tools.dottydoc.DocDriver;
+import dotty.tools.dottydoc.model.Package;
+import dotty.tools.dottydoc.util.OutputWriter;
+import java.util.Map;
+import java.util.List;
+import java.net.URL;
+
+/**
+ * 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 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,
+        List<URL> resources,
+        Map<String, Package> index
+    ) {
+        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

@@ -0,0 +1,49 @@
+package dotty.tools.dottydoc.api.scala
+
+import dotty.tools.dottydoc.DocDriver
+import dotty.tools.dottydoc.model.Package
+import dotty.tools.dottydoc.util.OutputWriter
+
+import scala.collection.Map
+import java.net.URL
+
+/**
+ * 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/core/AlternateConstructorsPhase.scala

@@ -0,0 +1,34 @@
+package dotty.tools
+package dottydoc
+package core
+
+import dotc.core.Contexts.Context
+
+import transform.DocMiniPhase
+import model._
+import model.internal._
+
+/** This DocMiniPhase adds the alternate constructors, currently defined as
+ *  methods with the name `<init>`, to the Entity#constructors list
+ */
+class AlternateConstructors extends DocMiniPhase {
+  def partitionMembers(ent: Entity with Constructors with Members): (List[List[ParamList]], List[Entity]) = {
+    val (constructors, members) = ent.members.partition(x => x.name == "<init>")
+
+    val paramLists: List[List[ParamList]] = constructors.collect {
+      case df: Def => df.paramLists
+    }
+
+    (ent.constructors ++ paramLists, members)
+  }
+
+  override def transformClass(implicit ctx: Context) = { case cls: ClassImpl =>
+    val (constructors, members) = partitionMembers(cls)
+    cls.copy(members = members, constructors = constructors)
+  }
+
+  override def transformCaseClass(implicit ctx: Context) = { case cc: CaseClassImpl =>
+    val (constructors, members) = partitionMembers(cc)
+    cc.copy(members = members, constructors = constructors)
+  }
+}