From c32ee91e83332fbfdeb32e03f73860eafff89cd6 Mon Sep 17 00:00:00 2001 From: Lex Spoon Date: Sun, 16 Mar 2008 18:24:54 +0000 Subject: Cleans up what scaladoc generates for synthetic... Cleans up what scaladoc generates for synthetic classes like scala.Int and scala.Any: - When generating API docs for the standard library, add synthetic classes to the indexes (all classes, all classes in package "scala", etc.) - When generating API docs for anything else, do not generate the HTML files for synthetic classes. Instead, link to the Scala home page, the same as with non-synthetic classes. --- .../scala/tools/nsc/doc/DefaultDocDriver.scala | 88 +++++++++++++++------- .../scala/tools/nsc/doc/ModelExtractor.scala | 4 +- src/compiler/scala/tools/nsc/doc/ModelFrames.scala | 5 +- src/compiler/scala/tools/nsc/doc/ModelToXML.scala | 3 +- src/compiler/scala/tools/nsc/symtab/Symbols.scala | 13 ++++ 5 files changed, 81 insertions(+), 32 deletions(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala b/src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala index 96e50ff67d..4e43852bf6 100644 --- a/src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala +++ b/src/compiler/scala/tools/nsc/doc/DefaultDocDriver.scala @@ -17,6 +17,8 @@ import scala.xml._ */ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToXML { import global._ + import definitions.{AnyClass, AnyRefClass} + object additions extends jcl.LinkedHashSet[Symbol] object additions0 extends ModelAdditions(global) { override def addition(sym: global.Symbol) = { @@ -31,6 +33,44 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX def init {} } + /** Add all top-level entities in ModelAdditions to allClasses */ + def addAdditionsToClasses() { + additions0.init + for (sym <- additions) { + val packSym = sym.enclosingPackage + if (packSym != NoSymbol) { + val pack = Package(packSym) + if (!(allClasses contains pack)) { + // don't emit an addition unless its package + // is already being scaladoced + } else { + val addition: Option[ClassOrObject] = + if (sym.isClass) + Some(new TopLevelClass(sym)) + else if (sym.isModule) + Some(new TopLevelObject(sym)) + else if (sym == definitions.AnyRefClass) { + // AnyRef is the only top-level type alias, so handle + // it specially instead of introducing general support for + // top-level aliases + Some(new TopLevelClass(sym)) + } + else + None + + addition match { + case None => + //println("skipping: " + sym) //DEBUG + case Some(addition) => + allClasses(pack) += addition + } + } + } else { + //println("no package found for: "+sym) //DEBUG + } + } + } + def process(units: Iterator[CompilationUnit]) { assert(global.definitions != null) @@ -62,12 +102,12 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX } } units.foreach(unit => f(null, unit.body)) + addAdditionsToClasses() for (p <- allClasses; d <- p._2) { symbols += d.sym for (pp <- d.sym.tpe.parents) subClasses(pp.typeSymbol) += d } - additions0.init copyResources val packages0 = sort(allClasses.keySet) new AllPackagesFrame with Frame { def packages = packages0 } @@ -122,29 +162,6 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX } } } - for (sym <- additions) sym match { - case sym: ClassSymbol => - val add = new TopLevelClass(sym) - new ClassContentFrame with Frame { - def clazz = add - def title = - add.kind + " " + add.name + " in package " + add.sym.owner.fullNameString('.') - } - case sym: TypeSymbol => - val add = new TopLevelClass(sym) - new ClassContentFrame with Frame { - def clazz = add - def title = - add.kind + " " + add.name + " in package " + add.sym.owner.fullNameString('.') - } - case sym: ModuleSymbol => - val add = new TopLevelObject(sym) - new ClassContentFrame with Frame { - def clazz = add - def title = - add.kind + " " + add.name + " in package " + add.sym.owner.fullNameString('.') - } - } new RootFrame with Frame } override def longList(entity: ClassOrObject, category: Category)(implicit from: Frame) : NodeSeq = category match { @@ -199,7 +216,8 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX object roots extends jcl.LinkedHashMap[String,String]; roots("classes") = "http://java.sun.com/j2se/1.5.0/docs/api"; roots("rt") = roots("classes"); - roots("scala-library") = "http://www.scala-lang.org/docu/files/api"; + private val SCALA_API_ROOT = "http://www.scala-lang.org/docu/files/api/"; + roots("scala-library") = SCALA_API_ROOT; private def keyFor(file: ZipFile): String = { var name = file.getName @@ -213,8 +231,16 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX // {Text(string + " - ")}; override def hasLink0(sym: Symbol): Boolean = { if (sym == NoSymbol) return false; - val ret = super.hasLink0(sym) && (additions.contains(sym) || symbols.contains(sym)); - if (ret) return true; + if (sym == AnyRefClass) { + // AnyRefClass is a type alias, so the following logic + // does not work. AnyClass should have a link in + // the same cases as AnyRefClass, so test it instead. + return hasLink(AnyClass) + } + if (super.hasLink0(sym) && symbols.contains(sym)) + return true; + if (SyntheticClasses contains sym) + return true; if (sym.toplevelClass == NoSymbol) return false; val clazz = sym.toplevelClass.asInstanceOf[ClassSymbol]; import scala.tools.nsc.io._; @@ -254,8 +280,16 @@ abstract class DefaultDocDriver extends DocDriver with ModelFrames with ModelToX override def rootFor(sym: Symbol): String = { assert(sym != NoSymbol) + if (sym == definitions.AnyRefClass) { + // AnyRefClass is a type alias, so the following logic + // does not work. AnyClass should have the same root, + // so use it instead. + return rootFor(definitions.AnyClass) + } if (sym.toplevelClass == NoSymbol) return super.rootFor(sym) if (symbols.contains(sym.toplevelClass)) return super.rootFor(sym) + if (SyntheticClasses contains sym) + return SCALA_API_ROOT val clazz = sym.toplevelClass.asInstanceOf[ClassSymbol] import scala.tools.nsc.io._; clazz.classFile match { diff --git a/src/compiler/scala/tools/nsc/doc/ModelExtractor.scala b/src/compiler/scala/tools/nsc/doc/ModelExtractor.scala index a3fcfa223b..3a25b5163e 100644 --- a/src/compiler/scala/tools/nsc/doc/ModelExtractor.scala +++ b/src/compiler/scala/tools/nsc/doc/ModelExtractor.scala @@ -182,7 +182,7 @@ trait ModelExtractor { override def kind = "object" } - case class Package(override val sym: ModuleSymbol) extends Entity(sym) { + case class Package(override val sym: Symbol) extends Entity(sym) { override def kind = "package" override def name = fullName('.') } @@ -397,7 +397,7 @@ trait ModelExtractor { // override def plural = "Additional Constructors"; } val Objects = Category("Object")(_.isModule); - val Classes = new Category("Class")(_.isClass) { + val Classes = new Category("Class")(sym => sym.isClass || (sym == definitions.AnyRefClass)) { override def plural = "Classes" } val Values = new Category("Value")(e => e.isValue && e.hasFlag(symtab.Flags.ACCESSOR)) { diff --git a/src/compiler/scala/tools/nsc/doc/ModelFrames.scala b/src/compiler/scala/tools/nsc/doc/ModelFrames.scala index 5d7ba96397..3b3a093c2d 100644 --- a/src/compiler/scala/tools/nsc/doc/ModelFrames.scala +++ b/src/compiler/scala/tools/nsc/doc/ModelFrames.scala @@ -19,6 +19,7 @@ import scala.xml.{NodeSeq, Text, Unparsed, Utility} trait ModelFrames extends ModelExtractor { import DocUtil._ def settings: doc.Settings + import global.definitions.{AnyClass, AnyRefClass} val SyntheticClasses = new scala.collection.mutable.HashSet[global.Symbol]; { @@ -110,12 +111,12 @@ trait ModelFrames extends ModelExtractor { import symtab.Flags def urlFor(sym: Symbol): String = sym match { - case sym : TypeSymbol if sym == definitions.AnyRefClass => - urlFor0(sym, sym) + FILE_EXTENSION_HTML case psym : ModuleSymbol if psym.isPackage => urlFor0(sym, sym) + FILE_EXTENSION_HTML case sym if !hasLink(sym) => null + case sym if sym == AnyRefClass => + urlFor0(sym, sym) + FILE_EXTENSION_HTML case msym: ModuleSymbol => urlFor0(sym, sym) + FILE_EXTENSION_HTML case csym: ClassSymbol => diff --git a/src/compiler/scala/tools/nsc/doc/ModelToXML.scala b/src/compiler/scala/tools/nsc/doc/ModelToXML.scala index de41df11c6..c7895ab25f 100644 --- a/src/compiler/scala/tools/nsc/doc/ModelToXML.scala +++ b/src/compiler/scala/tools/nsc/doc/ModelToXML.scala @@ -14,6 +14,7 @@ import scala.xml._ */ trait ModelToXML extends ModelExtractor { import global._ + import definitions.AnyRefClass import DocUtil._ // decode entity into XML. type Frame @@ -36,7 +37,7 @@ trait ModelToXML extends ModelExtractor { val url = urlFor(entity) if (url == null) { // external link (handled by script.js) val (href, attr) = - if (entity.isClass) + if (entity.isClass || (entity==AnyRefClass)) ("", entity.owner.fullNameString('/') + '/' + entity.nameString) else ("#" + entity.nameString, entity.owner.fullNameString('/')) diff --git a/src/compiler/scala/tools/nsc/symtab/Symbols.scala b/src/compiler/scala/tools/nsc/symtab/Symbols.scala index e863e12766..2a928f2e4f 100644 --- a/src/compiler/scala/tools/nsc/symtab/Symbols.scala +++ b/src/compiler/scala/tools/nsc/symtab/Symbols.scala @@ -855,6 +855,19 @@ trait Symbols { info.baseClasses.tail.takeWhile(sc ne) } + /** The package containing this symbol, or NoSymbol if there + * is not one. */ + def enclosingPackage: Symbol = + if (this == NoSymbol) this else { + var packSym = this.owner + while ((packSym != NoSymbol) + && !packSym.isPackageClass) + packSym = packSym.owner + if (packSym != NoSymbol) + packSym = packSym.linkedModuleOfClass + packSym + } + /** The top-level class containing this symbol */ def toplevelClass: Symbol = if (owner.isPackageClass) { -- cgit v1.2.3