diff options
author | Heather Miller <heather.miller@epfl.ch> | 2011-09-17 20:24:26 +0000 |
---|---|---|
committer | Heather Miller <heather.miller@epfl.ch> | 2011-09-17 20:24:26 +0000 |
commit | 7343e044153fb5f91028878fe1ddf341f62b37ee (patch) | |
tree | 5e2c6a27794c7204ce5cf9ecfdcdd7fc99dd9ee4 /src | |
parent | fef6649b31d58e2cc239518cb031d39e1ac58b70 (diff) | |
download | scala-7343e044153fb5f91028878fe1ddf341f62b37ee.tar.gz scala-7343e044153fb5f91028878fe1ddf341f62b37ee.tar.bz2 scala-7343e044153fb5f91028878fe1ddf341f62b37ee.zip |
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.
Diffstat (limited to 'src')
5 files changed, 55 insertions, 0 deletions
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 |