- Class Nothing is - together with class
- Null - at the bottom of the
- Scala type
- hierarchy.
-
-
- Type Nothing is a subtype of every other type
- (including Null); there
- exist no instances of this type. Even though type
- Nothing is empty, it is nevertheless useful as a
- type parameter. For instance, the Scala library defines a value
- Nil of type
- List[Nothing]. Because lists
- are covariant in Scala,
- this makes Nil an
- instance of List[T], for
- any element type T.
-
- Type Null is a subtype of all reference types; its
- only instance is the null reference.
- Since Null is not a subtype of value types,
- null is not a member of any such type. For instance,
- it is not possible to assign null to a variable of
- type Int.
-
"""
-
- /*******************************************************************/
- /* Documentation for Any */
-
- addition(AnyClass);
- comments(AnyClass) = """
-
- Class Any is the root of the Scala class hierarchy. Every class in a
- Scala execution
- environment inherits directly or indirectly from this class.
- Class Any has two direct subclasses:
- AnyRef and
- AnyVal.
-
"""
-
- addition(Any_equals);
- comments(Any_equals) = """
- This method is used to compare the receiver object (this)
- with the argument object (arg0) for equivalence.
-
-
It is reflexive: for any instance x of type Any,
- x.equals(x) should return true.
-
It is symmetric: for any instances x and y of type
- Any, x.equals(y) should return true if and only
- if y.equals(x) returns true.
-
It is transitive: for any instances
- x, y, and z of type AnyRef
- if x.equals(y) returns true and
- y.equals(z) returns
- true, then x.equals(z) should return true.
-
-
-
-
- If you override this method, you should verify that
- your implementation remains an equivalence relation.
- Additionally, when overriding this method it is often necessary to
- override hashCode to ensure that objects that are
- "equal" (o1.equals(o2) returns true)
- hash to the same Int
- (o1.hashCode.equals(o2.hashCode)).
-
- @param arg0 the object to compare against this object for equality.
- @return true if the receiver object is equivalent to the argument; false otherwise.
-
- """
-
- addition(Any_==);
- comments(Any_==) = """
- o == arg0 is the same as o.equals(arg0).
-
- @param arg0 the object to compare against this object for equality.
- @return true if the receiver object is equivalent to the argument; false otherwise.
-
- """
-
- addition(Any_!=);
- comments(Any_!=) = """
- o != arg0 is the same as !(o == (arg0)).
-
- @param arg0 the object to compare against this object for dis-equality.
- @return false if the receiver object is equivalent to the argument; true otherwise.
-
- """
-
- addition(Any_toString);
- comments(Any_toString) = """
- Returns a string representation of the object.
-
- The default representation is platform dependent.
-
- @return a string representation of the object.
-
- """
-
- addition(Any_asInstanceOf);
- comments(Any_asInstanceOf) = """
- This method is used to cast the receiver object to be of type T0.
-
-
Note that the success of a cast at runtime is modulo Scala's
- erasure semantics. Therefore the expression
- 1.asInstanceOf[String] will throw a
- ClassCastException at runtime, while the expression
- List(1).asInstanceOf[List[String]] will not. In the
- latter example, because the type argument is erased as part of
- compilation it is not possible to check whether the contents of
- the list are of the requested typed.
-
- @throws ClassCastException if the receiver object is not an
- instance of erasure of type T0.
- @return the receiver object.
-
"""
-
- addition(Any_isInstanceOf);
- comments(Any_isInstanceOf) = """
- This method is used to test whether the dynamic type of the receiver object is T0.
-
-
Note that the test result of the test is modulo Scala's erasure
- semantics. Therefore the expression
- 1.isInstanceOf[String] will return
- false, while the expression
- List(1).isInstanceOf[List[String]] will return
- true. In the latter example, because the type
- argument is erased as part of compilation it is not possible to
- check whether the contents of the list are of the requested typed.
-
- @return true if the receiver object is an
- instance of erasure of type T0; false otherwise.
- """
-
- addition(Any_hashCode);
- comments(Any_hashCode) = """
- Returns a hash code value for the object.
-
-
- The default hashing algorithm is platform dependent.
-
- Note that it is allowed for two objects to have identical hash
- codes (o1.hashCode.equals(o2.hashCode)) yet not be
- equal (o1.equals(o2) returns false). A
- degenerate implementation could always return 0.
- However, it is required that if two objects are equal
- (o1.equals(o2) returns true) that they
- have identical hash codes
- (o1.hashCode.equals(o2.hashCode)). Therefore, when
- overriding this method, be sure to verify that the behavior is
- consistent with the equals method.
-
- Class AnyRef is the root class of all
- reference types.
-
"""
-
- addition(Object_==);
- comments(Object_==) = """
- o == arg0 is the same as if (o eq null) arg0 eq null else o.equals(arg0).
-
- @param arg0 the object to compare against this object for equality.
- @return true if the receiver object is equivalent to the argument; false otherwise.
-
- """
-
- addition(Object_ne);
- comments(Object_ne) = """
- o.ne(arg0) is the same as !(o.eq(arg0)).
-
- @param arg0 the object to compare against this object for reference dis-equality.
- @return false if the argument is not a reference to the receiver object; true otherwise.
-
- """
-
-
- addition(Object_finalize);
- comments(Object_finalize) = """
- This method is called by the garbage collector on the receiver object when garbage
- collection determines that there are no more references to the object.
-
- The details of when and if the finalize method are
- invoked, as well as the interaction between finalize
- and non-local returns and exceptions, are all platform dependent.
-
- """
-
- addition(Object_clone);
- comments(Object_clone) = """
- This method creates and returns a copy of the receiver object.
-
-
- The default implementation of the clone method is platform dependent.
-
- @return a copy of the receiver object.
-
- """
-
- addition(Object_getClass);
- comments(Object_getClass) = """
- Returns a representation that corresponds to the dynamic class of the receiver object.
-
-
- The nature of the representation is platform dependent.
-
- @return a representation that corresponds to the dynamic class of the receiver object.
-
- """
-
- addition(Object_notify);
- comments(Object_notify) = """
- Wakes up a single thread that is waiting on the receiver object's monitor.
- """
-
- addition(Object_notifyAll);
- comments(Object_notifyAll) = """
- Wakes up all threads that are waiting on the receiver object's monitor.
- """
-
- addition(Object_eq);
- comments(Object_eq) = """
- This method is used to test whether the argument (arg0) is a reference to the
- receiver object (this).
-
-
- The eq method implements an
- equivalence relation on non-null instances of
- AnyRef:
-
-
It is reflexive: for any non-null instance x of type AnyRef,
- x.eq(x) returns true.
-
It is symmetric: for any non-null instances x and y of type
- AnyRef, x.eq(y) returns true if and only
- if y.eq(x) returns true.
-
It is transitive: for any non-null instances
- x, y, and z of type AnyRef
- if x.eq(y) returns true and
- y.eq(z) returns
- true, then x.eq(z) returns true.
-
- Additionally, the eq method has three other properties.
-
-
It is consistent: for any non-null instances x and y of type AnyRef,
- multiple invocations of x.eq(y) consistently returns true
- or consistently returns false.
-
For any non-null instance x of type AnyRef,
- x.eq(null) and null.eq(x) returns false.
-
null.eq(null) returns true.
-
-
-
-
When overriding the equals or
- hashCode methods, it is important to ensure that
- their behavior is consistent with reference equality. Therefore,
- if two objects are references to each other (o1 eq
- o2), they should be equal to each other (o1 ==
- o2) and they should hash to the same value
- (o1.hashCode == o2.hashCode).
-
- @param arg0 the object to compare against this object for reference equality.
- @return true if the argument is a reference to the receiver object; false otherwise.
-
- """
-
- /*******************************************************************/
-
- addition(AnyValClass);
- comments(AnyValClass) = """
-
- Class AnyVal is the root class of all
- value types.
-
-
- AnyVal has a fixed number subclasses, which
- describe values which are not implemented as objects in the
- underlying host system.
-
-
- Classes Double,
- Float,
- Long,
- Int,
- Char,
- Short, and
- Byte are together called
- numeric value types.
- Classes Byte,
- Short, or
- Char
- are called subrange types. Subrange types, as well as
- Int and
- Long are called
- integer types, whereas
- Float and
- Double are called
- floating point types.
-
- Class """ + sym.name + """ belongs to the value
- classes whose instances are not represented as objects by the
- underlying host system. There is an implicit conversion from
- instances of """ + sym.name + """ to instances of
- runtime.Rich""" + sym.name + """ which
- provides useful non-primitive operations. All value classes inherit
- from class AnyVal.
-
-
- Values """ + maxValue + """ and """ + minValue + """
- are in defined in object scala.Math.
-
- Class """ + sym.name + """ implements the
- boxing/unboxing from/to value types.
-
-
- Boxing and unboxing enable value types to be treated as objects;
- they provide a unified view of the type system wherein a value
- of any type can ultimately be treated as an object.
-
"""
- };
- //("Float" :: "Long" :: "Number" :: "Integer" :: Nil).foreach(boxedValDescr);
-*/
- object exceptions extends collection.JavaConversions.JMapWrapper[String,(Symbol,String)](
- new java.util.TreeMap()) {
- def f(name: String) {
- this("Predef." + name) = (definitions.PredefModule, name)
- }
- f("IndexOutOfBoundsException")
- f("NoSuchElementException")
- f("NullPointerException")
- f("UnsupportedOperationException")
- }
-}
diff --git a/src/compiler/scala/tools/nsc/doc/ModelExtractor.scala b/src/compiler/scala/tools/nsc/doc/ModelExtractor.scala
deleted file mode 100644
index e6c44c7cf..000000000
--- a/src/compiler/scala/tools/nsc/doc/ModelExtractor.scala
+++ /dev/null
@@ -1,453 +0,0 @@
-/* NSC -- new Scala compiler
- * Copyright 2007-2009 LAMP/EPFL
- * @author Sean McDirmid
- */
-// $Id$
-
-package scala.tools.nsc
-package doc
-
-import scala.collection.mutable
-import compat.Platform.{EOL => LINE_SEPARATOR}
-
-
-/** This class attempts to reverse engineer source code intent from compiler
- * symbol objects.
- *
- * @author Sean McDirmid
- */
-trait ModelExtractor {
- val global: Global
- import global._
- def settings: doc.Settings
-
- def assert(b: Boolean) {
- if (!b) throw new Error
- }
-
- def assert(b: Boolean, message: Any) {
- if (!b) throw new Error(message.toString)
- }
-
- case class Tag(tag: String, option: String, body: String)
-
- case class Comment(body: String, attributes: List[Tag]) {
- def decodeAttributes = {
- val map = new mutable.LinkedHashMap[String, List[(String, String)]] {
- override def default(key: String) = Nil
- }
- attributes.foreach(a => {
- map(a.tag) = map(a.tag) ::: List((a.option, a.body))
- });
- map
- }
- }
- protected def decode(sym: Symbol) =
- if (sym == definitions.ScalaObjectClass || sym == definitions.ObjectClass)
- definitions.AnyRefClass
- else sym match {
- case sym: ModuleClassSymbol => sym.sourceModule
- case sym => sym
- }
-
- protected def decodeComment(comment0: String): Comment = {
- val comment = { // discard outmost comment delimiters if present
- val begin = if (comment0 startsWith "/**") 3 else 0
- val end = comment0.length - (if (comment0 endsWith "*/") 2 else 0)
- comment0.substring(begin, end)
- }
- val tok = new java.util.StringTokenizer(comment, LINE_SEPARATOR)
- val buf = new StringBuilder
- type AttrDescr = (String, String, StringBuilder)
- val attributes = new collection.mutable.ListBuffer[AttrDescr]
- var attr: AttrDescr = null
- while (tok.hasMoreTokens) {
- val s = tok.nextToken.replaceFirst("\\p{Space}?\\*", "")
- val mat1 = pat1.matcher(s)
- if (mat1.matches) {
- attr = (mat1.group(1), null, new StringBuilder(mat1.group(2)))
- //if (kind != CONSTRUCTOR)
- attributes += attr
- } else {
- val mat2 = pat2.matcher(s)
- if (mat2.matches) {
- attr = (mat2.group(1), mat2.group(2), new StringBuilder(mat2.group(3)))
- //if (kind != CLASS)
- attributes += attr
- } else if (attr ne null)
- attr._3.append(s + LINE_SEPARATOR)
- else
- buf.append(s + LINE_SEPARATOR)
- }
- }
- Comment(buf.toString, attributes.toList.map({x => Tag(x._1,x._2,x._3.toString)}))
- }
-
- sealed abstract class Entity(val sym: Symbol) {
- private[ModelExtractor] def sym0 = sym
-
- override def toString = sym.toString
- def comment: Option[String] = global.comments.get(sym)
- // comments decoded, now what?
- def attributes = sym.annotations
- def decodeComment: Option[Comment] = {
- val comment0 = this.comment
- if (comment0.isEmpty) None
- else Some(ModelExtractor.this.decodeComment(comment0.get.trim))
- }
- protected def accessQualified(core: String, qual: String) = core match {
- case "public" => "" // assert(qual == null); "";
- case core => core + (if (qual == null) "" else "[" + qual + "]")
- }
-
- def flagsString = {
- import symtab.Flags
- //val isLocal = sym.hasFlag(Flags.LOCAL)
- val x =
- if (sym hasFlag Flags.PRIVATE) "private"
- else if (sym hasFlag Flags.PROTECTED) "protected"
- else "public"
- var string = accessQualified(x,
- if (sym hasFlag Flags.LOCAL) "this"
- else if (sym.privateWithin != null && sym.privateWithin != NoSymbol)
- sym.privateWithin.nameString
- else null
- )
- def f(flag: Int, str: String) {
- if (sym hasFlag flag) string = string + " " + str
- }
- f(Flags.IMPLICIT, "implicit")
- f(Flags.SEALED, "sealed")
- f(Flags.OVERRIDE, "override")
- f(Flags.CASE, "case")
- if (!sym.isTrait) f(Flags.ABSTRACT, "abstract")
- if (!sym.isModule) f(Flags.FINAL, "final")
- if (!sym.isTrait) f(Flags.DEFERRED, "abstract")
- string.trim
- }
- def listName = name
- def name = sym.nameString
- def fullName(sep: Char) = sym.fullNameString(sep)
- def kind: String
- def header { }
- def typeParams: List[TypeParam] = Nil
- def valueParams: List[List[ValueParam]] = Nil
- def resultType: Option[Type] = None
- def parents: Iterable[Type] = Nil
- def lo: Option[Type] = sym.info match {
- case TypeBounds(lo, hi) if decode(lo.typeSymbol) != definitions.NothingClass => Some(lo)
- case _ => None
- }
- def hi: Option[Type] = sym.info match {
- case TypeBounds(lo, hi) if decode(hi.typeSymbol) != definitions.AnyClass => Some(hi)
- case _ => None
- }
- def variance = {
- import symtab.Flags._
- if (sym hasFlag COVARIANT) "+"
- else if (sym hasFlag CONTRAVARIANT) "-"
- else ""
- }
- def overridden: Iterable[Symbol] = Nil
- }
-
- class ValueParam(sym: Symbol) extends Entity(sym) {
- override def resultType = Some(sym.tpe)
- //def kind = if (sym.isPublic) "val" else "";
- def kind = ""
- }
-
- class ConstructorParam(sym: Symbol) extends ValueParam(sym) {
- override protected def accessQualified(core: String, qual: String) = core match {
- case "public" => "val"
- case "protected" => super.accessQualified(core,qual) + " val"
- case "private" if qual == "this" => ""
- case core => super.accessQualified(core, qual)
- }
- }
-
- def ValueParam(sym: Symbol) = new ValueParam(sym)
- class TypeParam(sym: Symbol) extends Entity(sym) {
- def kind = ""
- }
- def TypeParam(sym: Symbol) = new TypeParam(sym)
-
- trait Clazz extends ClassOrObject {
- private def csym = sym.asInstanceOf[TypeSymbol]
- override def typeParams = csym.typeParams.map(TypeParam)
- override def valueParams = {
- if (constructorArgs.isEmpty) Nil
- else constructorArgs.valuesIterator.toList :: Nil
- }
- def isTrait = csym.isTrait
- override def kind = if (sym.isTrait) "trait" else "class"
- }
-
- trait Object extends ClassOrObject {
- override def kind = "object"
- }
-
- case class Package(override val sym: Symbol) extends Entity(sym) {
- override def kind = "package"
- override def name = fullName('.')
- }
-
- trait TopLevel extends ClassOrObject
- class TopLevelClass (sym: Symbol) extends Entity(sym) with TopLevel with Clazz
- class TopLevelObject(sym: Symbol) extends Entity(sym) with TopLevel with Object {
- override def attributes = sym.moduleClass.annotations
- }
-
- def compare(pathA: List[ClassOrObject], pathB: List[ClassOrObject]): Int = {
- var pA = pathA
- var pB = pathB
- while (true) {
- if (pA.isEmpty) return -1
- if (pB.isEmpty) return +1
- val diff = pA.head.name compare pB.head.name
- if (diff != 0) return diff
- pA = pA.tail
- pB = pB.tail
- }
- 0
- }
-
- def isAccessible(sym: Symbol): Boolean = {
- import symtab.Flags._
- settings.memberaccess.value match {
- case "private" => sym.isPublic || (sym hasFlag PROTECTED) || (sym hasFlag PRIVATE)
- case "protected" => sym.isPublic || (sym hasFlag PROTECTED)
- case "public" => sym.isPublic
- case _ => false
- }
- }
-
- trait ClassOrObject extends Entity {
- def path: List[ClassOrObject] = this :: Nil
- override def listName = path map (_.name) mkString "."
-
- object freshParents extends mutable.LinkedHashSet[Type] {
- this ++= sym.tpe.parents
- this.toList foreach (this --= _.parents)
- }
- object constructorArgs extends mutable.LinkedHashMap[Symbol, ValueParam] {
- import symtab.Flags._
- sym.constrParamAccessors.filter(arg => ! (arg hasFlag SYNTHETIC)).foreach(arg => {
- val str = flagsToString(arg.flags)
- assert((arg hasFlag PRIVATE) && (arg hasFlag LOCAL), arg)
- val argName = arg.name.toString.trim
- val actual = sym.tpe.decls.iterator.find(e => {
- val eName = e.name.toString.trim;
- argName == eName && {
- val str = flagsToString(e.flags);
- !e.hasFlag(LOCAL);
- }
- });
- val param = actual getOrElse arg
- this(param) = new ConstructorParam(param)
- });
- }
- object decls extends mutable.LinkedHashMap[Symbol, Member] {
- sym.tpe.decls.iterator.foreach(e => {
- if (!constructorArgs.contains(e)) {
- val m = Member(e)
- if (!m.isEmpty && !this.contains(e)) this.put(e, m.get)
- }
- });
- }
- def members0(f: Symbol => Boolean) = decls.filterKeys(f).valuesIterator.toList
- def members(c: Category): Iterable[Member] = members0(c.f)
- object inherited extends mutable.LinkedHashMap[Symbol, List[Member]]() {
- override def default(tpe: Symbol) = Nil
- for (m <- sym.tpe.members if !sym.tpe.decls.iterator.contains(m) &&
- (Values.f(m) || Methods.f(m))) {
- val o = m.overridingSymbol(sym)
- if (o == NoSymbol) {
- val parent = decode(m.enclClass)
- val mo = Member(m)
- if (!mo.isEmpty) {
- this(parent) = mo.get :: this(parent)
- }
- }
- }
- }
- override def parents = freshParents
- abstract class Member(sym: Symbol) extends Entity(sym) {
- private def overriding = sym.allOverriddenSymbols
- override def comment = super.comment match {
- case ret @ Some(comment) =>
- ret
- case None =>
- val o = overriding.find(comments.contains)
- o.map(comments.apply)
- }
- }
- abstract class ValDef(sym: Symbol) extends Member(sym) {
- override def resultType = Some(resultType0)
- protected def resultType0: Type
- override def overridden: Iterable[Symbol] = {
- var ret: mutable.LinkedHashSet[Symbol] = null
- for (parent <- ClassOrObject.this.parents) {
- val sym0 = sym.overriddenSymbol(parent.typeSymbol)
- if (sym0 != NoSymbol) {
- if (ret == null) ret = new mutable.LinkedHashSet[Symbol];
- ret += sym0
- }
- }
- if (ret == null) Nil else ret
- }
- }
- case class Def(override val sym : TermSymbol) extends ValDef(sym) {
- override def resultType0 = sym.tpe.finalResultType
- override def typeParams = sym.tpe.typeParams.map(TypeParam)
- override def valueParams = methodArgumentNames.get(sym) match {
- case Some(argss) if argss.length > 1 || (!argss.isEmpty && !argss(0).isEmpty) =>
- argss map (_.map(ValueParam))
- case _ =>
- var i = 0
- val ret = for (tpe <- sym.tpe.paramTypes) yield {
- val ret = sym.newValueParameter(sym.pos, newTermName("arg" + i));
- ret setInfo tpe
- i += 1
- ValueParam(ret)
- }
- if (ret.isEmpty) Nil
- else ret :: Nil
- }
- override def kind = "def"
- }
- case class Val(override val sym: TermSymbol) extends ValDef(sym) {
- import symtab.Flags._
- def resultType0: Type = sym.tpe
- override def kind: String =
- if (sym hasFlag ACCESSOR) {
- val setterName = nme.getterToSetter(sym.name)
- val setter = sym.owner.info.decl(setterName)
- val lazyMod = if (sym hasFlag LAZY) "lazy " else ""
- lazyMod + (if (setter == NoSymbol) "val" else "var")
- } else {
- assert(sym hasFlag JAVA)
- if (sym hasFlag FINAL) "val" else "var"
- }
- }
-
- case class AbstractType(override val sym: Symbol) extends Member(sym) {
- override def kind = "type"
- }
-
- abstract class NestedClassOrObject(override val sym: Symbol) extends Member(sym) with ClassOrObject {
- override def path: List[ClassOrObject] = ClassOrObject.this.path ::: super.path
- }
-
- case class NestedClass(override val sym: ClassSymbol) extends NestedClassOrObject(sym) with Clazz
-
- case class NestedObject(override val sym: ModuleSymbol) extends NestedClassOrObject(sym) with Object {
- override def attributes = sym.moduleClass.annotations
- }
-
- def isVisible(sym: Symbol): Boolean = {
- import symtab.Flags._
- if (sym.isLocalClass) return false
- if (sym.isLocal) return false
- if (sym.isPrivateLocal) return false
- // the next line used to return !inIDE - now it returns true. The underlying
- // logic being applied here is somewhat mysterious (if PRIVATE return isVisible == true?)
- // but changing it causes the docgenerator.scala test case to break, so I leave as-is.
- if (sym hasFlag PRIVATE) return true
- if (sym hasFlag SYNTHETIC) return false
- if (sym hasFlag BRIDGE) return false
- if ((sym.nameString indexOf "$") != -1) return false
- if ((sym hasFlag CASE) && sym.isMethod) return false
- true
- }
-
- def Member(sym: Symbol): Option[Member] = {
- import global._
- import symtab.Flags
- if (!isVisible(sym))
- None
- else if (!isAccessible(sym))
- None
- else if (sym hasFlag Flags.ACCESSOR) {
- if (sym.isSetter) return None;
- assert(sym.isGetter);
- Some[Member](new Val(sym.asInstanceOf[TermSymbol]))
- }
- else if (sym.isValue && !sym.isMethod && !sym.isModule) {
- if (!sym.hasFlag(Flags.JAVA)) {
- Console.println("SYM: " + sym + " " + sym.fullNameString('.'))
- Console.println("FLA: " + Flags.flagsToString(sym.flags))
- }
- assert(sym hasFlag Flags.JAVA)
- Some[Member](new Val(sym.asInstanceOf[TermSymbol]))
- }
- else if (sym.isValue && !sym.isModule) {
- val str = Flags.flagsToString(sym.flags)
- assert(sym.isMethod)
- Some[Member](new Def(sym.asInstanceOf[TermSymbol]))
- }
- else if (sym.isAliasType || sym.isAbstractType)
- Some(new AbstractType(sym))
- else if (sym.isClass)
- Some(new NestedClass(sym.asInstanceOf[ClassSymbol]))
- else if (sym.isModule)
- Some(new NestedObject(sym.asInstanceOf[ModuleSymbol]))
- else
- None
- }
-
- }
- case class Category(label: String)(g: Symbol => Boolean) {
- val f = g
- def plural = label + "s"
- }
- val Constructors = new Category("Additional Constructor")(e => e.isConstructor && !e.isPrimaryConstructor) {
- // override def plural = "Additional Constructors";
- }
- val Objects = Category("Object")(_.isModule);
- 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)) {
- override def plural = "Values and Variables"
- }
- val Methods = Category("Method")(e => e.isValue && e.isMethod && !e.isConstructor && !e.hasFlag(symtab.Flags.ACCESSOR));
- val Types = Category("Type")(e => e.isAliasType || e.isAbstractType);
-
- val categories = Constructors :: Types :: Values :: Methods :: Classes :: Objects :: Nil;
-
-
- import java.util.regex.Pattern
- // patterns for standard tags with 1 and 2 arguments
- private val pat1 = Pattern.compile(
- "[ \t]*@(author|deprecated|owner|pre|return|see|since|todo|version|ex|note)[ \t]*(.*)")
- private val pat2 = Pattern.compile(
- "[ \t]*@(exception|param|throws)[ \t]+(\\p{Graph}*)[ \t]*(.*)")
-
- def sort[E <: Entity](entities: Iterable[E]): Iterable[E] = {
- val set = new collection.immutable.TreeSet[E]()(new Ordering[E] {
- def compare(eA : E, eB: E): Int = {
- if (eA eq eB) return 0;
- (eA, eB) match {
- case (eA: ClassOrObject, eB: ClassOrObject) =>
- val diff = ModelExtractor.this.compare(eA.path, eB.path)
- if (diff!= 0) return diff
- case _ =>
- }
- if (eA.getClass != eB.getClass) {
- val diff = eA.getClass.getName.compare(eB.getClass.getName)
- assert(diff != 0)
- return diff
- }
- if (!eA.sym0.isPackage) {
- val diff = eA.sym0.nameString compare eB.sym0.nameString
- if (diff != 0) return diff
- }
- val diff0 = eA.sym0.fullNameString compare eB.sym0.fullNameString
- assert(diff0 != 0)
- diff0
- }
- })
- set ++ entities
- }
-}
diff --git a/src/compiler/scala/tools/nsc/doc/ModelFrames.scala b/src/compiler/scala/tools/nsc/doc/ModelFrames.scala
deleted file mode 100644
index 6a412b3a1..000000000
--- a/src/compiler/scala/tools/nsc/doc/ModelFrames.scala
+++ /dev/null
@@ -1,396 +0,0 @@
-/* NSC -- new Scala compiler
- * Copyright 2005-2009 LAMP/EPFL
- * @author Sean McDirmid
- */
-// $Id$
-
-package scala.tools.nsc
-package doc
-
-import java.io.{File, FileWriter}
-import scala.util.NameTransformer
-import scala.collection.mutable
-import scala.compat.Platform.{EOL => LINE_SEPARATOR}
-import scala.xml.{NodeSeq, Text, Unparsed, Utility}
-
-/** This class provides HTML document framing functionality.
- *
- * @author Sean McDirmid, Stephane Micheloud
- */
-trait ModelFrames extends ModelExtractor {
- import DocUtil._
- def settings: doc.Settings
- import global.definitions.{AnyClass, AnyRefClass}
-
- val SyntheticClasses = new scala.collection.mutable.HashSet[global.Symbol];
- {
- import global.definitions._
- global.definitions.init
- SyntheticClasses ++= List(
- NothingClass, NullClass, AnyClass, AnyRefClass, AnyValClass,
- //value classes
- BooleanClass, ByteClass, CharClass, IntClass, LongClass, ShortClass,
- FloatClass, DoubleClass, UnitClass)
- }
-
- val outdir = settings.outdir.value
- val windowTitle = settings.windowtitle.value
- val docTitle = load(settings.doctitle.value)
-
- val stylesheetSetting = settings.stylesheetfile
-
- def pageHeader = load(settings.pageheader.value)
- def pageFooter = load(settings.pagefooter.value)
- def pageTop = load(settings.pagetop.value)
- def pageBottom = load(settings.pagebottom.value)
-
- def contentFrame = "contentFrame"
- def classesFrame = "classesFrame"
- def modulesFrame = "modulesFrame"
-
- protected val FILE_EXTENSION_HTML = ".html"
- protected val NAME_SUFFIX_OBJECT = "$object"
- protected val NAME_SUFFIX_PACKAGE = "$package"
-
- def rootTitle = (
{docTitle}
);
- def rootDesc =
- (
{load("This document is the API specification for " + windowTitle)}
);
-
- final def hasLink(sym: global.Symbol): Boolean =
- if (sym == global.NoSymbol) false
- else if (hasLink0(sym)) true
- else hasLink(decode(sym.owner))
-
- def hasLink0(sym: global.Symbol): Boolean = true
-
- abstract class Frame extends UrlContext {
- { // just save.
- save(page(title, body, hasBody));
- }
- def path: String // relative to outdir
- def relative: String = {
- if (path eq null) return "foo"
- assert(path ne null)
- var idx = 0
- var ct = new StringBuilder
- while (idx != -1) {
- idx = path.indexOf('/', idx)
- //System.err.println(path + " idx=" + idx)
- ct.append(if (idx != -1) "../" else "")
- idx += (if (idx == -1) 0 else 1)
- }
- ct.toString
- }
- def save(nodes: NodeSeq) = {
- val path = this.path
- if (path.startsWith("http://")) throw new Error("frame: " + this)
- val path0 = outdir + File.separator + path + FILE_EXTENSION_HTML
- //if (settings.debug.value) inform("Writing XML nodes to " + path0)
- val file = new File(path0)
- val parent = file.getParentFile()
- if (!parent.exists()) parent.mkdirs()
- val writer = new FileWriter(file)
- val str = dtype + LINE_SEPARATOR + nodes.toString()
- writer.write(str, 0, str.length())
- writer.close()
- }
- protected def body: NodeSeq
- protected def title: String
- protected def hasBody = true
-
- //def urlFor(entity: Entity, target: String): NodeSeq
- def urlFor(entity: Entity): String = {
- val ret = this.urlFor(entity.sym)
- assert(ret != null);
- ret
- }
- def link(entity: Entity, target: String) = aref(urlFor(entity), target, entity.name)
- protected def shortHeader(entity: Entity): NodeSeq
- protected def longHeader(entity: Entity): NodeSeq
- import global._
- import symtab.Flags
-
- def urlFor(sym: Symbol): String = sym match {
- 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 =>
- urlFor0(sym, sym) + FILE_EXTENSION_HTML
- case _ =>
- val cnt = urlFor(decode(sym.owner))
- if (cnt == null) null else cnt + "#" + docName(sym)
- }
-
- def docName(sym: Symbol): String = {
- def javaParams(paramTypes: List[Type]): String = {
- def javaName(pt: Type): String = {
- val s = pt.toString
- val matVal = patVal.matcher(s)
- if (matVal.matches) matVal.group(1).toLowerCase
- else s.replaceAll("\\$", ".")
- }
- paramTypes.map(pt => javaName(pt)).mkString("(", ",", ")")
- }
- def scalaParams(paramTypes: List[Type]): String = {
- def scalaName(pt: Type): String = pt.toString.replaceAll(" ", "")
- paramTypes.map(pt => scalaName(pt)).mkString("(", ",", ")")
- }
- java.net.URLEncoder.encode(sym.nameString +
- (sym.tpe match {
- case MethodType(params, _) =>
- val paramTypes = params map (_.tpe)
- if (sym hasFlag Flags.JAVA) javaParams(paramTypes)
- else scalaParams(paramTypes)
- case PolyType(_, MethodType(params, _)) =>
- val paramTypes = params map (_.tpe)
- if (sym hasFlag Flags.JAVA) javaParams(paramTypes)
- else scalaParams(paramTypes)
- case _ => ""
- }), encoding)
- }
-
- def urlFor0(sym: Symbol, orig: Symbol): String =
- (if (sym == NoSymbol) "XXX"
- else if (sym.owner.isPackageClass) rootFor(sym) + pkgPath(sym)
- else urlFor0(decode(sym.owner), orig) + "." + NameTransformer.encode(Utility.escape(sym.nameString))
- ) +
- (sym match {
- case msym: ModuleSymbol =>
- if (msym hasFlag Flags.PACKAGE) NAME_SUFFIX_PACKAGE
- else NAME_SUFFIX_OBJECT
- case csym: ClassSymbol if csym.isModuleClass =>
- if (csym hasFlag Flags.PACKAGE) NAME_SUFFIX_PACKAGE
- else NAME_SUFFIX_OBJECT
- case _ =>
- ""
- })
- }
- def pkgPath(sym : global.Symbol) = sym.fullNameString('/') match {
- case "" => "_empty_"
- case path => path
- }
-
- protected def rootFor(sym: global.Symbol) = ""
-
- abstract class AllPackagesFrame extends Frame {
- override lazy val path = "modules"
- override lazy val title = "List of all packages"
- def packages: Iterable[Package]
- override def body: NodeSeq =
- (
{
- var seq: NodeSeq = NodeSeq.Empty
- cmnt.decodeAttributes.foreach{
- case (tag, xs) =>
- seq = seq ++
- {decodeTag(tag)}
++ {xs.flatMap{
- case (option,body) =>
{
- if (option == null) NodeSeq.Empty;
- else decodeOption(tag, option);
- }{ tag match {
- case "see" => resolveSee(entity.sym, body.trim)
- case _ => parse(body)
- }}
- }}
- };
- seq
- }
;
-
-
{parse(cmnt.body)}
- {attrs}
-
- }
-
- /**
- * Try to be smart about @see elements. If the body looks like a link, turn it into
- * a link. If it can be resolved in the symbol table, turn it into a link to the referenced
- * entity.
- */
- private def resolveSee(owner: Symbol, body: String)(implicit frame: Frame): NodeSeq = {
- /** find a class either in the root package, in the current class or in the current package. */
- def findClass(clsName: String): Symbol = {
- try { definitions.getClass(clsName) } catch {
- case f: FatalError =>
- try { definitions.getMember(owner, clsName.toTypeName) } catch {
- case f: FatalError =>
- definitions.getMember(owner.enclosingPackage, clsName.toTypeName)
- }
- }
- }
-
- if (body.startsWith("http://")
- || body.startsWith("https://")
- || body.startsWith("www")) {
- // a link
- body.split(" ") match {
- case Seq(href, txt, rest @ _*) =>
- {txt}{rest}
- case _ =>
- {body}
- }
- } else try {
- // treat it like a class or member reference
- body.split("#") match {
- case Seq(clazz, member) =>
- val clazzSym = if (clazz.length == 0) owner.enclClass else findClass(clazz)
- link(definitions.getMember(clazzSym, member), body)
- case Seq(clazz, _*) =>
- link(findClass(clazz), body)
- case _ =>
- parse(body)
- }
- } catch {
- case f: FatalError =>
- log("Error resolving @see: " + f.toString)
- parse(body)
- }
- }
-
- def classBody(entity: ClassOrObject)(implicit from: Frame): NodeSeq =
-
- {categories.mkXML("","\n","")(c => shortList(entity, c)) : NodeSeq}
- {categories.mkXML("","\n","")(c => longList(entity, c)) : NodeSeq}
- ;
-
- def longList(entity: ClassOrObject, category: Category)(implicit from: Frame): NodeSeq = {
- val xs = entity.members(category)
- if (!xs.iterator.hasNext)
- NodeSeq.Empty
- else Group(
-
-
{Text(category.label)} Details
-
-
{xs.mkXML("","\n","")(m => longHeader(m))}
)
- }
-
- def shortList(entity: ClassOrObject, category: Category)(implicit from: Frame): NodeSeq = {
- val xs = entity.members(category)
- var seq: NodeSeq = NodeSeq.Empty
- if (xs.iterator.hasNext) {
- // alphabetic
- val set = new scala.collection.immutable.TreeSet[entity.Member]()(new Ordering[entity.Member] {
- def compare(mA : entity.Member, mB: entity.Member): Int =
- if (mA eq mB) 0
- else {
- val diff = mA.name compare mB.name
- if (diff != 0) diff
- else {
- val diff0 = mA.hashCode - mB.hashCode
- assert(diff0 != 0, mA.name)
- diff0
- }
- }
- })++xs
- seq = seq ++
- {link(decode(entity.sym))}
- {bodyFor(entity) ++ extendsFor(entity)}
- {
- entity.resultType match {
- case Some(PolyType(_, ConstantType(v))) => Text(" = " + v.escapedStringValue)
- case _ => NodeSeq.Empty
- }
- }
- {
- val cmnt = entity.decodeComment
- if (cmnt.isEmpty) NodeSeq.Empty
- else shortComment(cmnt.get)
- }
-
-
-
- import java.util.regex.Pattern
- // pattern detecting first line of comment (see ticket #224)
- private val pat = Pattern.compile("[ \t]*(/\\*)[ \t]*")
-
- /** Ticket #224
- * Write the first sentence as a short summary of the method, as scaladoc
- * automatically places it in the method summary table (and index).
- * (see http://java.sun.com/j2se/javadoc/writingdoccomments/)
- */
- def shortComment(cmnt: Comment): NodeSeq = {
- val lines = cmnt.body split "
"
- val first =
- if (lines.length < 2)
- lines(0)
- else {
- val line0 = lines(0)
- val mat = pat matcher line0
- if (mat.matches()) line0 + lines(1)
- else line0
- }
-
{parse(first/*cmnt.body*/)}
- }
-
- def attrsFor(entity: Entity)(implicit from: Frame): NodeSeq = {
- def attrFor(attr: AnnotationInfo): Node = {
- val buf = new StringBuilder
- val AnnotationInfo(tpe, args, nvPairs) = attr
- val name = link(decode(tpe.typeSymbol))
- if (!args.isEmpty)
- buf.append(args.mkString("(", ",", ")"))
- if (!nvPairs.isEmpty)
- for (((name, value), index) <- nvPairs.zipWithIndex) {
- if (index > 0)
- buf.append(", ")
- buf.append(name).append(" = ").append(value)
- }
- Group(name ++ Text(buf.toString))
- }
- def toGroup(x: AnnotationInfo): Node = Group(Text("@") ++ attrFor(x) ++ )
- if (entity.sym.hasFlag(symtab.Flags.CASE)) NodeSeq.Empty
- else NodeSeq fromSeq (entity.attributes map toGroup)
- }
-}
diff --git a/src/compiler/scala/tools/nsc/doc/Processor.scala b/src/compiler/scala/tools/nsc/doc/Processor.scala
new file mode 100644
index 000000000..67bc6dd18
--- /dev/null
+++ b/src/compiler/scala/tools/nsc/doc/Processor.scala
@@ -0,0 +1,56 @@
+/* NSC -- new Scala compiler -- Copyright 2007-2009 LAMP/EPFL */
+
+// $Id$
+
+package scala.tools.nsc
+package doc
+
+import reporters.Reporter
+
+/** A documentation processor controls the process of generating Scala documentation, which is as follows.
+ *
+ * * A simplified compiler instance (with only the front-end phases enabled) is created, and additional
+ * ''sourceless'' comments are registered.
+ * * Documentable files are compiled, thereby filling the compiler's symbol table.
+ * * A documentation model is extracted from the post-compilation compiler's symbol table.
+ * * A generator is used to transform the model into the correct final format (HTML).
+ *
+ * A processor contains a single compiler instantiated from the processor's settings. Each call to the `run` method
+ * uses the same compiler instance with the same symbol table. In particular, this implies that the scaladoc site
+ * obtained from a call to `run` will contain documentation about files compiled during previous calls to the same
+ * processor's `run` method.
+ *
+ * @param reporter The reporter to which both documentation and compilation errors will be reported.
+ * @param settings The settings to be used by the documenter and compiler for generating documentation.
+ *
+ * @author Gilles Dubochet */
+class Processor(val reporter: Reporter, val settings: doc.Settings) { processor =>
+
+ /** The unique compiler instance used by this processor and constructed from its `settings`. */
+ object compiler extends Global(settings, reporter) {
+ override protected def computeInternalPhases() {
+ phasesSet += syntaxAnalyzer
+ phasesSet += analyzer.namerFactory
+ phasesSet += analyzer.typerFactory
+ phasesSet += superAccessors
+ phasesSet += pickler
+ phasesSet += refchecks
+ }
+ override def onlyPresentation = true
+ lazy val addSourceless = {
+ val sless = new SourcelessComments { val global = compiler }
+ comments ++= sless.comments
+ }
+ }
+
+ /** Creates a scaladoc site for all symbols defined in this call's `files`, as well as those defined in `files` of
+ * previous calls to the same processor.
+ * @param files The list of paths (relative to the compiler's source path, or absolute) of files to document. */
+ def document(files: List[String]): Unit = {
+ (new compiler.Run()) compile files
+ compiler.addSourceless
+ if (!reporter.hasErrors)
+ (new html.SiteFactory(reporter, settings)) generate (new model.EntityFactory(compiler, settings)).makeModel
+ }
+
+}
diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala
index 8a0d61fe3..299bee65b 100644
--- a/src/compiler/scala/tools/nsc/doc/Settings.scala
+++ b/src/compiler/scala/tools/nsc/doc/Settings.scala
@@ -11,19 +11,14 @@ import java.io.File
import java.lang.System
class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
+
/** scaladoc specific options */
- val memberaccess = ChoiceSetting ("-access", "Show only public, protected/public (default) or all classes and members",
- List("public", "protected", "private"), "protected")
- val pagebottom = StringSetting ("-bottom", "pagebottom", "Include bottom text for each page", "")
- val doccharset = StringSetting ("-charset", "doccharset", "Charset for cross-platform viewing of generated documentation.", "")
- val doctitle = StringSetting ("-doctitle", "doctitle", "Include title for the overview page", "Scala 2 API Specification")
- val pagefooter = StringSetting ("-footer", "pagefooter", "Include footer text for each page", "")
- val pageheader = StringSetting ("-header", "pageheader", "Include header text for each page", "")
- val linksource = BooleanSetting ("-linksource", "Generate source in HTML")
- val nocomment = BooleanSetting ("-nocomment", "Suppress description and tags, generate only declarations.")
- val stylesheetfile = StringSetting ("-stylesheetfile", "stylesheetfile", "File to change style of the generated documentation", "style.css")
- val pagetop = StringSetting ("-top", "pagetop", "Include top text for each page", "")
- val windowtitle = StringSetting ("-windowtitle", "windowtitle", "Specify window title of generated HTML documentation", "Scala 2")
+ val docformat = ChoiceSetting ("-doc-format", "Selects to which format documentation is rendered", List("html"), "html")
+ val doctitle = StringSetting ("-doc-title", "doc-title", "Include title for the overview page", "Scala 2 API")
+
+ // working around issue described in r18708.
+ suppressVTWarn.value = true
+
// working around issue described in r18708.
suppressVTWarn.value = true
diff --git a/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala b/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
new file mode 100644
index 000000000..fb1db33b4
--- /dev/null
+++ b/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
@@ -0,0 +1,379 @@
+/* NSC -- new Scala compiler -- Copyright 2007-2009 LAMP/EPFL */
+
+package scala.tools.nsc
+package doc
+
+import scala.collection._
+
+/**
+ * This class contains comments to all symbols which pre-exist in Scala, such as Any, Nothing, ...
+ * It also contains a HashSet of the given symbols
+ * The comments are to be added to a HashMap called comments, which resides in the Global.scala file
+ * @author Manohar Jonnalagedda, Stephane Micheloud, Sean McDirmid, Geoffrey Washburn
+ * @version 1.0
+ */
+abstract class SourcelessComments {
+
+ val global: Global
+
+ import global._
+ import definitions._
+
+ lazy val comments = {
+
+ val comment = mutable.HashMap.empty[Symbol, String]
+
+ comment(NothingClass) = """
+ /**
+ * Class Nothing is - together with class
+ * Null - at the bottom of the
+ * Scala type
+ * hierarchy.
+ *
+ *
+ * Type Nothing is a subtype of every other type
+ * (including Null); there
+ * exist no instances of this type. Even though type
+ * Nothing is empty, it is nevertheless useful as a
+ * type parameter. For instance, the Scala library defines a value
+ * Nil of type
+ * List[Nothing]. Because lists
+ * are covariant in Scala,
+ * this makes Nil an
+ * instance of List[T], for
+ * any element type T.
+ *
+ * Type Null is a subtype of all reference types; its
+ * only instance is the null reference.
+ * Since Null is not a subtype of value types,
+ * null is not a member of any such type. For instance,
+ * it is not possible to assign null to a variable of
+ * type Int.
+ *
*/
+ """
+
+ /*******************************************************************/
+ /* Documentation for Any */
+
+ comment(AnyClass) = """
+ /**
+ * Class Any is the root of the Scala class hierarchy. Every class in a
+ * Scala execution
+ * environment inherits directly or indirectly from this class.
+ * Class Any has two direct subclasses:
+ * AnyRef and
+ * AnyVal.
+ *
*/
+ """
+
+ comment(Any_equals) = """
+ /** This method is used to compare the receiver object (this)
+ * with the argument object (arg0) for equivalence.
+ *
+ *
It is reflexive: for any instance x of type Any,
+ * x.equals(x) should return true.
+ *
It is symmetric: for any instances x and y of type
+ * Any, x.equals(y) should return true if and only
+ * if y.equals(x) returns true.
+ *
It is transitive: for any instances
+ * x, y, and z of type AnyRef
+ * if x.equals(y) returns true and
+ * y.equals(z) returns
+ * true, then x.equals(z) should return true.
+ *
+ *
+ *
+ *
+ * If you override this method, you should verify that
+ * your implementation remains an equivalence relation.
+ * Additionally, when overriding this method it is often necessary to
+ * override hashCode to ensure that objects that are
+ * "equal" (o1.equals(o2) returns true)
+ * hash to the same Int
+ * (o1.hashCode.equals(o2.hashCode)).
+ *
+ * @param arg0 the object to compare against this object for equality.
+ * @return true if the receiver object is equivalent to the argument; false otherwise.
+ *
*/
+ """
+
+ comment(Any_==) = """
+ /** `o == arg0` is the same as `o.equals(arg0)`.
+ *
+ * @param arg0 the object to compare against this object for equality.
+ * @return `true` if the receiver object is equivalent to the argument; `false` otherwise.
+ *
*/
+ """
+
+ comment(Any_!=) = """
+ /** `o != arg0` is the same as `!(o == (arg0))`.
+ *
+ * @param arg0 the object to compare against this object for dis-equality.
+ * @return `false` if the receiver object is equivalent to the argument; `true` otherwise.
+ *
*/
+ """
+
+ comment(Any_toString) = """
+ /** Returns a string representation of the object.
+ *
+ * The default representation is platform dependent.
+ *
+ * @return a string representation of the object.
+ *
*/
+ """
+
+ comment(Any_asInstanceOf) = """
+ /**This method is used to cast the receiver object to be of type T0.
+ *
+ *
Note that the success of a cast at runtime is modulo Scala's
+ * erasure semantics. Therefore the expression
+ * 1.asInstanceOf[String] will throw a
+ * ClassCastException at runtime, while the expression
+ * List(1).asInstanceOf[List[String]] will not. In the
+ * latter example, because the type argument is erased as part of
+ * compilation it is not possible to check whether the contents of
+ * the list are of the requested typed.
+ *
+ * @throws ClassCastException if the receiver object is not an
+ * instance of erasure of type T0.
+ * @return the receiver object.
+ *
*/
+ """
+
+ comment(Any_isInstanceOf) = """
+ /** This method is used to test whether the dynamic type of the receiver object is T0.
+ *
+ *
Note that the test result of the test is modulo Scala's erasure
+ * semantics. Therefore the expression
+ * 1.isInstanceOf[String] will return
+ * false, while the expression
+ * List(1).isInstanceOf[List[String]] will return
+ * true. In the latter example, because the type
+ * argument is erased as part of compilation it is not possible to
+ * check whether the contents of the list are of the requested typed.
+ *
+ * @return true if the receiver object is an
+ * instance of erasure of type T0; false otherwise. */
+ """
+
+ comment(Any_hashCode) = """
+ /** Returns a hash code value for the object.
+ *
+ *
+ * The default hashing algorithm is platform dependent.
+ *
+ * Note that it is allowed for two objects to have identical hash
+ * codes (o1.hashCode.equals(o2.hashCode)) yet not be
+ * equal (o1.equals(o2) returns false). A
+ * degenerate implementation could always return 0.
+ * However, it is required that if two objects are equal
+ * (o1.equals(o2) returns true) that they
+ * have identical hash codes
+ * (o1.hashCode.equals(o2.hashCode)). Therefore, when
+ * overriding this method, be sure to verify that the behavior is
+ * consistent with the equals method.
+ *
+ *
+ *
+ * @return the hash code value for the object.
+ *
+ * Class AnyRef is the root class of all
+ * reference types.
+ *
*/
+ """
+
+ comment(Object_==) = """
+ /** o == arg0 is the same as if (o eq null) arg0 eq null else o.equals(arg0).
+ *
+ * @param arg0 the object to compare against this object for equality.
+ * @return true if the receiver object is equivalent to the argument; false otherwise.
+ *
*/
+ """
+
+ comment(Object_ne) = """
+ /** o.ne(arg0) is the same as !(o.eq(arg0)).
+ *
+ * @param arg0 the object to compare against this object for reference dis-equality.
+ * @return false if the argument is not a reference to the receiver object; true otherwise.
+ *
*/
+ """
+
+
+ comment(Object_finalize) = """
+ /** This method is called by the garbage collector on the receiver object when garbage
+ * collection determines that there are no more references to the object.
+ *
+ * The details of when and if the finalize method are
+ * invoked, as well as the interaction between finalize
+ * and non-local returns and exceptions, are all platform dependent.
+ *
*/
+ """
+
+ comment(Object_clone) = """
+ /** This method creates and returns a copy of the receiver object.
+ *
+ *
+ * The default implementation of the clone method is platform dependent.
+ *
+ * @return a copy of the receiver object.
+ *
*/
+ """
+
+ comment(Object_getClass) = """
+ /** Returns a representation that corresponds to the dynamic class of the receiver object.
+ *
+ *
+ * The nature of the representation is platform dependent.
+ *
+ * @return a representation that corresponds to the dynamic class of the receiver object.
+ *
*/
+ """
+
+ comment(Object_notify) = """
+ /** Wakes up a single thread that is waiting on the receiver object's monitor. */
+ """
+
+ comment(Object_notifyAll) = """
+ /** Wakes up all threads that are waiting on the receiver object's monitor. */
+ """
+
+ comment(Object_eq) = """
+ /** This method is used to test whether the argument (arg0) is a reference to the
+ * receiver object (this).
+ *
+ *
+ * The eq method implements an
+ * equivalence relation on non-null instances of
+ * AnyRef:
+ *
+ *
It is reflexive: for any non-null instance x of type AnyRef,
+ * x.eq(x) returns true.
+ *
It is symmetric: for any non-null instances x and y of type
+ * AnyRef, x.eq(y) returns true if and only
+ * if y.eq(x) returns true.
+ *
It is transitive: for any non-null instances
+ * x, y, and z of type AnyRef
+ * if x.eq(y) returns true and
+ * y.eq(z) returns
+ * true, then x.eq(z) returns true.
+ *
+ * Additionally, the eq method has three other properties.
+ *
+ *
It is consistent: for any non-null instances x and y of type AnyRef,
+ * multiple invocations of x.eq(y) consistently returns true
+ * or consistently returns false.
+ *
For any non-null instance x of type AnyRef,
+ * x.eq(null) and null.eq(x) returns false.
+ *
null.eq(null) returns true.
+ *
+ *
+ *
+ *
When overriding the equals or
+ * hashCode methods, it is important to ensure that
+ * their behavior is consistent with reference equality. Therefore,
+ * if two objects are references to each other (o1 eq
+ * o2), they should be equal to each other (o1 ==
+ * o2) and they should hash to the same value
+ * (o1.hashCode == o2.hashCode).
+ *
+ * @param arg0 the object to compare against this object for reference equality.
+ * @return true if the argument is a reference to the receiver object; false otherwise.
+ * */
+ """
+
+ /*******************************************************************/
+
+ comment(AnyValClass) = """
+ /**
+ * Class AnyVal is the root class of all
+ * value types.
+ *
+ *
+ * AnyVal has a fixed number subclasses, which
+ * describe values which are not implemented as objects in the
+ * underlying host system.
+ *
+ *
+ * Classes Double,
+ * Float,
+ * Long,
+ * Int,
+ * Char,
+ * Short, and
+ * Byte are together called
+ * numeric value types.
+ * Classes Byte,
+ * Short, or
+ * Char
+ * are called subrange types. Subrange types, as well as
+ * Int and
+ * Long are called
+ * integer types, whereas
+ * Float and
+ * Double are called
+ * floating point types.
+ *
*/
+ """
+
+ comment(BooleanClass) = """
+ /**
+ * Class Boolean has only two values: true
+ * and false.
+ *
+ * Class """ + sym.name + """ belongs to the value
+ * classes whose instances are not represented as objects by the
+ * underlying host system. There is an implicit conversion from
+ * instances of """ + sym.name + """ to instances of
+ * runtime.Rich""" + sym.name + """ which
+ * provides useful non-primitive operations. All value classes inherit
+ * from class AnyVal.
+ *
+ *
+ * Values """ + maxValue + """ and """ + minValue + """
+ * are in defined in object scala.Math.
+ *
*/
+ """
+ }
+
+ comment
+ }
+
+}
diff --git a/src/compiler/scala/tools/nsc/doc/TODO.txt b/src/compiler/scala/tools/nsc/doc/TODO.txt
new file mode 100644
index 000000000..dbdca88eb
--- /dev/null
+++ b/src/compiler/scala/tools/nsc/doc/TODO.txt
@@ -0,0 +1,19 @@
+= TODO in Scaladoc =
+
+== Model extractor ==
+
+
+
+== Parser ==
+
+ * Report more than one error per Scaladoc comment. This is caused by the reporter being used, and the fact that all errors are positioned on the documented symbol.
+ * Maintain position information, and use it in error messages (currently all positions are on symbol being documented)
+ * Parse wiki list syntax
+ * Parse wiki table syntax
+ * Parse URL links
+ * Parse symbol (class or method) links
+
+== HTML generator ==
+
+
+
\ No newline at end of file
diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala
new file mode 100644
index 000000000..e05ab2f3f
--- /dev/null
+++ b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala
@@ -0,0 +1,150 @@
+/* NSC -- new Scala compiler
+ * Copyright 2007-2009 LAMP/EPFL
+ * @author David Bernard, Manohar Jonnalagedda
+ */
+
+package scala.tools.nsc
+package doc
+package html
+
+import model._
+import comment._
+
+import java.io.File
+import scala.xml.dtd.{DocType, PublicID}
+import xml.{Unparsed, XML, NodeSeq}
+
+/** An html page that is part of a Scaladoc site.
+ * @author David Bernard
+ * @author Gilles Dubochet */
+abstract class HtmlPage { thisPage =>
+
+ /** The path of this page, relative to the API site. `path.tail` is a list of folder names leading to this page (from
+ * closest package to one-above-root package), `path.head` is the file name of this page. Note that `path` has a
+ * length of at least one. */
+ def path: List[String]
+
+ /** The title of this page. */
+ protected def title: String
+
+ /** Additional header elements (links, scripts, meta tags, etc.) required for this page. */
+ protected def headers: NodeSeq
+
+ /** The body of this page. */
+ protected def body: NodeSeq
+
+ /** 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. */
+ def writeFor(site: SiteFactory): Unit = {
+ val pageFile = new File(site.siteRoot, thisPage.path.reverse.mkString("/"))
+ val pageFolder = pageFile.getParentFile
+ if (!pageFolder.exists) pageFolder.mkdirs()
+ val doctype =
+ DocType("html", PublicID("-//W3C//DTD XHTML 1.1//EN", "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"), Nil)
+ val html =
+
+
+ { title }
+
+ { headers }
+
+ { body }
+
+ XML.save(pageFile.getPath, html, site.encoding, xmlDecl = false, doctype = doctype)
+ }
+
+ def templateToPath(tpl: TemplateEntity): List[String] = {
+ def downPacks(pack: Package): List[String] =
+ if (pack.isRootPackage) Nil else (pack.name :: downPacks(pack.inTemplate))
+ def downInner(nme: String, tpl: TemplateEntity): (String, Package) = {
+ tpl.inTemplate match {
+ case inPkg: Package => (nme + ".html", inPkg)
+ case inTpl => downInner(doName(inTpl) + "$" + nme, inTpl)
+ }
+ }
+ def doName(tpl: TemplateEntity): String =
+ tpl.name + (if (tpl.isObject) "$" else "")
+ val (file, pack) =
+ tpl match {
+ case p: Package => ("package.html", p)
+ case _ => downInner(doName(tpl), tpl)
+ }
+ file :: downPacks(pack)
+ }
+
+ /** A relative link from this page to some destination class entity.
+ * @param destEntity The class or object entity that the link will point to. */
+ def relativeLinkTo(destClass: TemplateEntity): String =
+ relativeLinkTo(templateToPath(destClass))
+
+ /** A relative link from this page to some destination page in the Scaladoc site.
+ * @param destPage The page that the link will point to. */
+ def relativeLinkTo(destPage: HtmlPage): String = {
+ relativeLinkTo(destPage.path)
+ }
+
+ /** A relative link from this page to some destination path.
+ * @param destPath The path that the link will point to. */
+ def relativeLinkTo(destPath: List[String]): String = {
+ def relativize(from: List[String], to: List[String]): List[String] = (from, to) match {
+ case (f :: fs, t :: ts) if (f == t) => // both paths are identical to that point
+ relativize(fs, ts)
+ case (fss, tss) =>
+ List.fill(fss.length - 1)("..") ::: tss
+ }
+ relativize(thisPage.path.reverse, destPath.reverse).mkString("/")
+ }
+
+ /** Transforms an optional comment into an styled HTML tree representing its body if it is defined, or into an empty
+ * node sequence if it is not. */
+ def commentToHtml(comment: Option[Comment]): NodeSeq =
+ (comment map (commentToHtml(_))) getOrElse NodeSeq.Empty
+
+ /** Transforms a comment into an styled HTML tree representing its body. */
+ def commentToHtml(comment: Comment): NodeSeq =
+ bodyToHtml(comment.body)
+
+ def bodyToHtml(body: Body): NodeSeq =
+ body.blocks flatMap (blockToHtml(_))
+
+ def blockToHtml(block: Block): NodeSeq = block match {
+ case Title(in, 1) =>
{ inlineToHtml(in) }
+ case Title(in, 2) =>
{ inlineToHtml(in) }
+ case Title(in, 3) =>
{ inlineToHtml(in) }
+ case Title(in, _) =>
{ inlineToHtml(in) }
+ case Paragraph(in) =>
{ inlineToHtml(in) }
+ case Code(data) =>
{ Unparsed(data) }
+ case UnorderedList(items) =>
+
{items map { i =>
{ blockToHtml(i) }
}}
+ case OrderedList(items) =>
+ {items map { i =>
{ blockToHtml(i) }
}}
+ case DefinitionList(items) =>
+
{items map { case (t, d) =>
{ inlineToHtml(t) }
{ blockToHtml(d) }
} }
+ case HorizontalRule() =>
+
+ }
+
+ def inlineToHtml(inl: Inline): NodeSeq = inl match {
+ //case URLLink(url, text) => {if(text.isEmpty)url else inlineSeqsToXml(text)}
+ case Chain(items) => items flatMap (inlineToHtml(_))
+ case Italic(in) => { inlineToHtml(in) }
+ case Bold(in) => { inlineToHtml(in) }
+ case Underline(in) => { inlineToHtml(in) }
+ case Superscript(in) => { inlineToHtml(in) }
+ case Subscript(in) => { inlineToHtml(in) }
+ case Link(raw) => Unparsed(raw)//error("link not supported") // TODO
+ case Monospace(text) => { Unparsed(text) }
+ case Text(text) => Unparsed(text)
+ }
+
+ def typeToHtml(tpe: model.TypeEntity): NodeSeq = {
+
+ // TODO: Generate links using tpe's refEntity map
+
+ xml.Text(tpe.name)
+
+ }
+
+}
diff --git a/src/compiler/scala/tools/nsc/doc/html/SiteFactory.scala b/src/compiler/scala/tools/nsc/doc/html/SiteFactory.scala
new file mode 100644
index 000000000..afbcd6613
--- /dev/null
+++ b/src/compiler/scala/tools/nsc/doc/html/SiteFactory.scala
@@ -0,0 +1,79 @@
+/* NSC -- new Scala compiler
+ * Copyright 2007-2009 LAMP/EPFL
+ * @author David Bernard, Manohar Jonnalagedda
+ */
+
+package scala.tools.nsc
+package doc
+package html
+
+import reporters.Reporter
+import model._
+
+import java.io.{FileOutputStream, File}
+import scala.collection._
+
+/** A class that can generate Scaladoc sites to some fixed root folder.
+ * @author David Bernard
+ * @author Gilles Dubochet */
+class SiteFactory(val reporter: Reporter, val settings: Settings) {
+
+ /** The character encoding to be used for generated Scaladoc sites. This value is currently always UTF-8. */
+ def encoding: String = "UTF-8"
+
+ /** The character encoding to be used for generated Scaladoc sites. This value is defined by the generator's
+ * settings. */
+ def siteRoot: File = new File(settings.outdir.value)
+
+ /** Generates the Scaladoc site for a model into the site toot. A scaladoc site is a set of HTML and related files
+ * that document a model extracted from a compiler run.
+ * @param model The model to generate in the form of a sequence of packages. */
+ def generate(modelRoot: Package): Unit = {
+
+ def copyResource(subPath: String) {
+ val buf = new Array[Byte](1024)
+ val in = getClass.getResourceAsStream("/scala/tools/nsc/doc/html/resource/" + subPath)
+ assert(in != null)
+ val dest = new File(siteRoot, subPath)
+ dest.getParentFile.mkdirs()
+ val out = new FileOutputStream(dest)
+ try {
+ var len = 0
+ while ({len = in.read(buf); len != -1})
+ out.write(buf, 0, len)
+ }
+ finally {
+ in.close()
+ out.close()
+ }
+ }
+
+ copyResource("lib/jquery.js")
+ copyResource("lib/index.css")
+ copyResource("lib/index.js")
+ copyResource("lib/template.css")
+ copyResource("lib/template.js")
+ copyResource("lib/class.png")
+ copyResource("lib/class_big.png")
+ copyResource("lib/object.png")
+ copyResource("lib/object_big.png")
+ copyResource("lib/trait.png")
+ copyResource("lib/trait_big.png")
+ copyResource("lib/package.png")
+ copyResource("lib/package_big.png")
+
+ new page.Index(modelRoot) writeFor this
+
+ val written = mutable.HashSet.empty[DocTemplateEntity]
+
+ def writeTemplate(tpl: DocTemplateEntity): Unit = {
+ new page.Template(tpl) writeFor this
+ written += tpl
+ tpl.templates filter { t => !(written contains t) } map (writeTemplate(_))
+ }
+
+ writeTemplate(modelRoot)
+
+ }
+
+}
diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala
new file mode 100644
index 000000000..ec408f363
--- /dev/null
+++ b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala
@@ -0,0 +1,77 @@
+/* NSC -- new Scala compiler
+ * Copyright 2007-2009 LAMP/EPFL
+ * @author David Bernard, Manohar Jonnalagedda
+ */
+
+package scala.tools.nsc
+package doc
+package html
+package page
+
+import model._
+
+import scala.collection._
+import scala.xml._
+
+class Index(modelRoot: Package) extends HtmlPage {
+
+ def path = List("index.html")
+
+ def title = "Scaladoc: all classes and objects"
+
+ def headers =
+
+
+
+
+
+ def body =
+
+
+ ImmutableMapAdaptor
+ [T ⊲ Int,Y]
+ extendsA[X] with C[Y] with B
+
+
+
+
This class can be used as an adaptor to create mutable maps from immutable map implementations. Only method empty has to be redefined if the immutable map on which this mutable map is originally based is not empty. empty is supposed to return the representation of an empty map.
+
A subtrait of collection.IndexedSeq which represents sequences that can be mutated.
+
The canonical builder for collections that are addable, i.e. that support an efficient + method which adds an element to the collection. Collections are built from their empty element using this + method.
U can be used as an adaptor to create mutable maps.
+
+
+
f can be used as an adaptor to create mutable maps from immutable map implementations. Only method empty has to be redefined.
+
+
+
b the immutable map on which this mutable map is originally based is not empty. empty is supposed to return the representation of an empty map.
+
+
+
override
protected
@inline
+
+
A subtrait of collection.IndexedSeq which represents sequences that can be mutated.
+
The canonical builder for collections that are addable, i.e. that support an efficient + method which adds an element to the collection. Collections are built from their empty element using this + method.
+
+
+
+
+
def
+
+ curry
+ (f: (A, B) => B,b: Double)(g: Int => B,c: Double)
+ :ImmutableMapAdaptor[A, B]
+
+
+
+
+
+
val
+
+ randomize
+ :ImmutableMapAdaptor[A, B]
+
+
+
+
A subtrait of collection.IndexedSeq which represents sequences that can be mutated.
+
The canonical builder for collections that are addable, i.e. that support an efficient + method which adds an element to the collection. Collections are built from their empty element using this + method.
+
+
+
+
+
object
+
+ babar
+
+
+
+
+
+
package
+
+ fantomette
+
+
+
+
A subtrait of collection.IndexedSeq which represents sequences that can be mutated.
+
The canonical builder for collections that are addable, i.e. that support an efficient + method which adds an element to the collection. Collections are built from their empty element using this + method.
+
+
+
+
+
+
Type Members
+
+
+
+
type
+
+ T
+ [T,U ⊲ Int]
+
+
+
+
A subtrait of collection.IndexedSeq which represents sequences that can be mutated.