Scaladoc diff-firendly output

Scaladoc can create raw content files that we can easily diff and spot
any modifications. There is a cool project by Stefan Zeiger to export
the scaladoc model in JSON, but with the language and scaladoc being so
quick to evolve, it'll be a pain to properly maintain. In the long-run,
the plan is to sample a couple of raw files on each build and email me
the diff. If I spot anything that may be wrong I can fix it, revert the
commit or at least file a bug.

For now, .html.raw files are generated on-demand, using
  ant -Dscaladoc.raw.output="yes" <targets>

Also added a script that will do the job of diff-ing.

Review by @jsuereth.

Conflicts:

	src/compiler/scala/tools/nsc/doc/Settings.scala

5 files changed, 42 insertions, 18 deletions

diff --git a/src/compiler/scala/tools/ant/Scaladoc.scala b/src/compiler/scala/tools/ant/Scaladoc.scala
index daa08ef8a7..2cada92c1e 100644
--- a/src/compiler/scala/tools/ant/Scaladoc.scala
+++ b/src/compiler/scala/tools/ant/Scaladoc.scala
@@ -150,6 +150,9 @@ class Scaladoc extends ScalaMatchingTask {
   /** Instruct the scaladoc tool to use the binary given to create diagrams */
   private var docDiagramsDotPath: Option[String] = None
 
+  /** Instruct the scaladoc to produce textual ouput from html pages, for easy diff-ing */
+  private var docRawOutput: Boolean = false
+
 
 /*============================================================================*\
 **                             Properties setters                             **
@@ -419,6 +422,11 @@ class Scaladoc extends ScalaMatchingTask {
   def setDiagramsDotPath(input: String) =
     docDiagramsDotPath = Some(input)
 
+  /** Set the `rawOutput` bit so Scaladoc also outputs text from each html file
+   *  @param input One of the flags `yes/no` or `on/off`. Default if no/off. */
+  def setRawOutput(input: String) =
+    docRawOutput = Flag.getBooleanValue(input, "rawOutput")
+
 /*============================================================================*\
 **                             Properties getters                             **
 \*============================================================================*/
@@ -616,6 +624,7 @@ class Scaladoc extends ScalaMatchingTask {
     docSettings.docImplicitsShowAll.value = docImplicitsShowAll
     docSettings.docDiagrams.value = docDiagrams
     docSettings.docDiagramsDebug.value = docDiagramsDebug
+    docSettings.docRawOutput.value = docRawOutput
     if(!docDiagramsDotPath.isEmpty) docSettings.docDiagramsDotPath.value = docDiagramsDotPath.get
 
     if (!docgenerator.isEmpty) docSettings.docgenerator.value = docgenerator.get
diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala
index 4458889d55..d7b61bc129 100644
--- a/src/compiler/scala/tools/nsc/doc/Settings.scala
+++ b/src/compiler/scala/tools/nsc/doc/Settings.scala
@@ -120,6 +120,11 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
     "dot" // by default, just pick up the system-wide dot
   )
 
+  val docRawOutput = BooleanSetting (
+    "-raw-output",
+    "For each html file, create another .html.raw file containing only the text. (can be used for quickly diffing two scaladoc outputs)"
+  )
+
   // Somewhere slightly before r18708 scaladoc stopped building unless the
   // self-type check was suppressed.  I hijacked the slotted-for-removal-anyway
   // suppress-vt-warnings option and renamed it for this purpose.
diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala
index e3da8bddea..4c9215f923 100644
--- a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala
@@ -13,7 +13,7 @@ import comment._
 import xml.{XML, NodeSeq}
 import xml.dtd.{DocType, PublicID}
 import scala.collection._
-import java.nio.channels.Channels
+import java.io.Writer
 
 /** An html page that is part of a Scaladoc site.
   * @author David Bernard
@@ -52,17 +52,19 @@ abstract class HtmlPage extends Page { thisPage =>
         </head>
         { body }
       </html>
-    val fos = createFileOutputStream(site)
-    val w = Channels.newWriter(fos.getChannel, site.encoding)
-    try {
+
+    writeFile(site) { (w: Writer) =>
       w.write("<?xml version='1.0' encoding='" + site.encoding + "'?>\n")
       w.write(doctype.toString + "\n")
       w.write(xml.Xhtml.toXhtml(html))
     }
-    finally {
-      w.close()
-      fos.close()
-    }
+
+    if (site.universe.settings.docRawOutput.value)
+      writeFile(site, ".raw") {
+        // we're only interested in the body, as this will go into the diff
+        _.write(body.text)
+      }
+
     //XML.save(pageFile.getPath, html, site.encoding, xmlDecl = false, doctype = doctype)
   }
 
diff --git a/src/compiler/scala/tools/nsc/doc/html/Page.scala b/src/compiler/scala/tools/nsc/doc/html/Page.scala
index c5bf3e0e37..72b62dd482 100644
--- a/src/compiler/scala/tools/nsc/doc/html/Page.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/Page.scala
@@ -8,6 +8,8 @@ package scala.tools.nsc.doc.html
 import scala.tools.nsc.doc.model._
 import java.io.{FileOutputStream, File}
 import scala.reflect.NameTransformer
+import java.nio.channels.Channels
+import java.io.Writer
 
 abstract class Page {
   thisPage =>
@@ -20,8 +22,8 @@ abstract class Page {
 
   def absoluteLinkTo(path: List[String]) = path.reverse.mkString("/")
 
-  def createFileOutputStream(site: HtmlFactory) = {
-    val file = new File(site.siteRoot, absoluteLinkTo(thisPage.path))
+  def createFileOutputStream(site: HtmlFactory, suffix: String = "") = {
+    val file = new File(site.siteRoot, absoluteLinkTo(thisPage.path) + suffix)
     val folder = file.getParentFile
     if (! folder.exists) {
       folder.mkdirs
@@ -29,6 +31,18 @@ abstract class Page {
     new FileOutputStream(file.getPath)
   }
 
+  def writeFile(site: HtmlFactory, suffix: String = "")(fn: Writer => Unit) = {
+    val fos = createFileOutputStream(site, suffix)
+    val w = Channels.newWriter(fos.getChannel, site.encoding)
+    try {
+      fn(w)
+    }
+    finally {
+      w.close()
+      fos.close()
+    }
+  }
+
   /** Writes this page as a file. The file's location is relative to the
     * generator's site root, and the encoding is also defined by the generator.
     * @param generator The generator that is writing this page. */
diff --git a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala
index 7edd4937c4..c5fe4da17a 100644
--- a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala
@@ -15,14 +15,8 @@ class IndexScript(universe: doc.Universe, index: doc.Index) extends Page {
   def path = List("index.js")
 
   override def writeFor(site: HtmlFactory) {
-    val stream = createFileOutputStream(site)
-    val writer = Channels.newWriter(stream.getChannel, site.encoding)
-    try {
-      writer.write("Index.PACKAGES = " + packages.toString() + ";")
-    }
-    finally {
-      writer.close
-      stream.close
+    writeFile(site) {
+      _.write("Index.PACKAGES = " + packages.toString() + ";")
     }
   }