Adds ability to document root package, as well ...

Adds ability to document root package, as well the first cut of an
introduction to the API. Contributed by Iain McGinniss during the
September doc spree.

6 files changed, 58 insertions, 1 deletions

diff --git a/build.xml b/build.xml
index 5425f1ad7a..857e945e50 100644
--- a/build.xml
+++ b/build.xml
@@ -592,6 +592,7 @@ QUICK BUILD (QUICK)
         <include name="**/*.swf"/>
         <include name="**/*.png"/>
         <include name="**/*.gif"/>        
+        <include name="**/*.txt"/>        
       </fileset>
     </copy>
     <touch file="${build-quick.dir}/compiler.complete" verbose="no"/>
@@ -1414,7 +1415,8 @@ DOCUMENTATION
       docsourceurl="https://lampsvn.epfl.ch/trac/scala/browser/scala/trunk/src/€{FILE_PATH}.scala#L1"
       docUncompilable="${src.dir}/library-aux"
       sourcepath="${src.dir}"
-      classpathref="pack.classpath">
+      classpathref="pack.classpath"
+      docRootContent="${build-docs.dir}/library/lib/rootdoc.txt"> 
       <src>
         <files includes="${src.dir}/actors"/>
         <files includes="${src.dir}/library/scala"/>
diff --git a/src/compiler/scala/tools/ant/Scaladoc.scala b/src/compiler/scala/tools/ant/Scaladoc.scala
index a4593b8f88..253d1dec5d 100644
--- a/src/compiler/scala/tools/ant/Scaladoc.scala
+++ b/src/compiler/scala/tools/ant/Scaladoc.scala
@@ -42,6 +42,7 @@ import scala.tools.nsc.reporters.{Reporter, ConsoleReporter}
  *  - `addparams`,
  *  - `deprecation`,
  *  - `docgenerator`,
+ *  - `docrootcontent`,
  *  - `unchecked`.
  *
  *  It also takes the following parameters as nested elements:
@@ -95,6 +96,9 @@ class Scaladoc extends ScalaMatchingTask {
   /** The fully qualified name of a doclet class, which will be used to generate the documentation. */
   private var docgenerator: Option[String] = None
 
+  /** The file from which the documentation content of the root package will be taken */
+  private var docrootcontent: Option[File] = None
+
   /** The document title of the generated HTML documentation. */
   private var doctitle: Option[String] = None
 
@@ -273,6 +277,16 @@ class Scaladoc extends ScalaMatchingTask {
     docgenerator = Some(input)
   }
 
+  /**
+   * Sets the `docrootcontent` attribute.
+   *
+   * @param input The file from which the documentation content of the root
+   * package will be taken.
+   */
+  def setDocrootcontent(input : File) {
+    docrootcontent = Some(input)
+  }
+
   /** Sets the `docversion` attribute.
    *
    *  @param input The value of `docversion`.
@@ -532,6 +546,7 @@ class Scaladoc extends ScalaMatchingTask {
     docSettings.deprecation.value = deprecation
     docSettings.unchecked.value = unchecked
     if (!docgenerator.isEmpty) docSettings.docgenerator.value = docgenerator.get
+    if (!docrootcontent.isEmpty) docSettings.docRootContent.value = docrootcontent.get.getAbsolutePath()
     log("Scaladoc params = '" + addParams + "'", Project.MSG_DEBUG)
 
     docSettings processArgumentString addParams
diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala
index cfd6635a76..6c74951156 100644
--- a/src/compiler/scala/tools/nsc/doc/Settings.scala
+++ b/src/compiler/scala/tools/nsc/doc/Settings.scala
@@ -81,6 +81,12 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
     "scala.tools.nsc.doc.html.Doclet"
   )
 
+  val docRootContent = PathSetting (
+    "-doc-root-content",
+    "The file from which the root package documentation should be imported.",
+    ""
+  )
+
   // 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/HtmlFactory.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala
index 49e39b717f..d629b73572 100644
--- a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala
@@ -99,6 +99,8 @@ class HtmlFactory(val universe: doc.Universe, index: doc.Index) {
     copyResource("lib/selected2.png")
     copyResource("lib/unselected.png")
 
+    copyResource("lib/rootdoc.txt")
+
     new page.Index(universe, index) writeFor this
     new page.IndexScript(universe, index) writeFor this
 
diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/rootdoc.txt b/src/compiler/scala/tools/nsc/doc/html/resource/lib/rootdoc.txt
new file mode 100644
index 0000000000..09be5da485
--- /dev/null
+++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/rootdoc.txt
@@ -0,0 +1,18 @@
+This is the documentation for the Scala standard library.
+
+Parts of the standard library are imported by default into all Scala source files: the [[scala]] package, and
+the contents of the [[scala.Predef]] object. In turn, these imports bring in parts of other packages throughout
+the standard library.
+
+The standard library is composed of the following fundamental packages:
+
+  - scala.[[scala.actors]] - A Erlang-style concurrency framework.
+  - scala.[[scala.collection]] - A powerful collections (data structures) framework with higher order functions for manipulation. Both [[scala.collection.mutable]] and [[scala.collection.immutable]] variants of most collection types exist, with the immutable collections being the default. Automatic parallelisation of manipulation operations is possible through the use of the [[scala.collection.parallel]] collection types.
+  - scala.[[scala.concurrent]] - Simplified execution of functions in separate threads.
+  - scala.[[scala.io]] - IO abstractions.
+  - scala.[[scala.math]] - Arbitrary precision numeric types and basic math functions.
+  - scala.[[scala.swing]] - UI toolkit, provides scala abstractions around the Java Swing toolkit.
+  - scala.[[scala.sys]] - Interaction with other processes and the operating system.
+  - scala.util.[[scala.util.matching]] - Text pattern matching using regular expressions.
+  - scala.util.[[scala.util.parsing]] - Framework for constructing parse trees. Includes a parser combinator library.
+  - scala.[[scala.xml]] - XML parsing, DOM manipulation and serialization.
diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
index a817ebddc8..ea77a55c16 100644
--- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
@@ -11,6 +11,8 @@ import scala.util.matching.Regex
 
 import symtab.Flags
 
+import io._
+
 import model.{ RootPackage => RootPackageEntity }
 
 /** This trait extracts all required information for documentation from compilation units */
@@ -332,6 +334,18 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
       val pack =
         if (bSym == RootPackage)
           new RootPackageImpl(bSym) {
+            override lazy val comment =
+              if(settings.docRootContent.isDefault) None
+              else {
+                import Streamable._
+                Path(settings.docRootContent.value) match {
+                  case f : File => {
+                    val rootComment = closing(f.inputStream)(is => parse(slurp(is), "", NoPosition))
+                    Some(rootComment)
+                  }
+                  case _ => None
+                }
+              }
             override val name = "root"
             override def inTemplate = this
             override def toRoot = this :: Nil