Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Adds ability to document root package

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.
  • Loading branch information...
commit 90b0f1b98a5e747bed19b4389bf46ba16fdf734d 1 parent eab63b1
Heather Miller heathermiller authored dcsobral committed
4 build.xml
View
@@ -606,6 +606,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"/>
@@ -1428,7 +1429,8 @@ DOCUMENTATION
docsourceurl="https://lampsvn.epfl.ch/trac/scala/browser/scala/branches/2.9.x/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"/>
87 src/compiler/scala/tools/ant/Scaladoc.scala
View
@@ -19,45 +19,38 @@ import scala.tools.nsc.Global
import scala.tools.nsc.doc.Settings
import scala.tools.nsc.reporters.{Reporter, ConsoleReporter}
-/** <p>
- * An Ant task to document Scala code.
- * </p>
- * <p>
- * This task can take the following parameters as attributes:
- * </p>
- * <ul>
- * <li>srcdir (mandatory),</li>
- * <li>srcref,</li>
- * <li>destdir,</li>
- * <li>classpath,</li>
- * <li>classpathref,</li>
- * <li>sourcepath,</li>
- * <li>sourcepathref,</li>
- * <li>bootclasspath,</li>
- * <li>bootclasspathref,</li>
- * <li>extdirs,</li>
- * <li>extdirsref,</li>
- * <li>encoding,</li>
- * <li>doctitle,</li>
- * <li>header,</li>
- * <li>footer,</li>
- * <li>top,</li>
- * <li>bottom,</li>
- * <li>addparams,</li>
- * <li>deprecation,</li>
- * <li>docgenerator,</li>
- * <li>unchecked.</li>
- * </ul>
- * <p>
- * It also takes the following parameters as nested elements:
- * </p>
- * <ul>
- * <li>src (for srcdir),</li>
- * <li>classpath,</li>
- * <li>sourcepath,</li>
- * <li>bootclasspath,</li>
- * <li>extdirs.</li>
- * </ul>
+/** An Ant task to document Scala code.
+ *
+ * This task can take the following parameters as attributes:
+ * - `srcdir` (mandatory),
+ * - `srcref`,
+ * - `destdir`,
+ * - `classpath`,
+ * - `classpathref`,
+ * - `sourcepath`,
+ * - `sourcepathref`,
+ * - `bootclasspath`,
+ * - `bootclasspathref`,
+ * - `extdirs`,
+ * - `extdirsref`,
+ * - `encoding`,
+ * - `doctitle`,
+ * - `header`,
+ * - `footer`,
+ * - `top`,
+ * - `bottom`,
+ * - `addparams`,
+ * - `deprecation`,
+ * - `docgenerator`,
+ * - `docrootcontent`,
+ * - `unchecked`.
+ *
+ * It also takes the following parameters as nested elements:
+ * - `src` (for srcdir),
+ * - `classpath`,
+ * - `sourcepath`,
+ * - `bootclasspath`,
+ * - `extdirs`.
*
* @author Gilles Dubochet, Stephane Micheloud
*/
@@ -103,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
@@ -283,7 +279,17 @@ class Scaladoc extends ScalaMatchingTask {
docgenerator = Some(input)
}
- /** Sets the <code>docversion</code> attribute.
+ /**
+ * 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 <code>docversion</code>.
*/
@@ -542,6 +548,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
6 src/compiler/scala/tools/nsc/doc/Settings.scala
View
@@ -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.
2  src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala
View
@@ -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
18 src/compiler/scala/tools/nsc/doc/html/resource/lib/rootdoc.txt
View
@@ -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.
14 src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
View
@@ -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
Please sign in to comment.
Something went wrong with that request. Please try again.