From 6ae78736589639f54d7987883cf3794cf69f6ac4 Mon Sep 17 00:00:00 2001 From: Gilles Dubochet Date: Wed, 23 Feb 2011 14:15:51 +0000 Subject: [scaladoc] Fully commented the Scaladoc model. --- .../scala/tools/nsc/doc/html/page/Template.scala | 6 +- .../scala/tools/nsc/doc/model/Entity.scala | 316 ++++++++++++++++----- .../scala/tools/nsc/doc/model/TreeEntity.scala | 27 +- .../scala/tools/nsc/doc/model/TreeFactory.scala | 47 +-- .../scala/tools/nsc/doc/model/TypeEntity.scala | 12 +- .../scala/tools/nsc/doc/model/ValueArgument.scala | 20 ++ .../scala/tools/nsc/doc/model/Visibility.scala | 39 +++ 7 files changed, 366 insertions(+), 101 deletions(-) create mode 100644 src/compiler/scala/tools/nsc/doc/model/ValueArgument.scala create mode 100644 src/compiler/scala/tools/nsc/doc/model/Visibility.scala (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala index 650a0e6e09..2bbd537481 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -518,16 +518,12 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { val str = defVal.expression val length = str.length var myXml: NodeSeq = NodeSeq.Empty - for( x <- defVal.refs) { - val from = x._1 - val to = x._2._2 + for( (from, (member, to)) <- defVal.refEntity.toSeq) { if (index < from) { myXml ++= stringToXml(str.substring(index,from)) index = from } - if (index == from) { - val member:Entity = x._2._1 member match { case mbr: DocTemplateEntity => val link = relativeLinkTo(mbr) diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index 4999b5496b..37485bccab 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -1,6 +1,7 @@ /* NSC -- new Scala compiler * Copyright 2007-2011 LAMP/EPFL - * @author Manohar Jonnalagedda + * @author Manohar Jonnalagedda + * @author Gilles Dubochet */ package scala.tools.nsc @@ -10,194 +11,381 @@ package model import scala.collection._ import comment._ -/** Some entity of the Scaladoc model. */ + +/** An entity in a Scaladoc universe. Entities are declarations in the program and correspond to symbols in the + * compiler. Entities model the following Scala concepts: + * - classes and traits; + * - objects and package; + * - constructors; + * - methods; + * - values, lazy values, and variables; + * - abstract type members and type aliases; + * - type and value parameters; + * - annotations. */ trait Entity { + + /** The name of the entity. Note that the name does not qualify this entity uniquely; use its `qualifiedName` + * instead. */ def name : String + + /** The qualified name of the entity. This is this entity's name preceded by the qualified name of the template + * of which this entity is a member. The qualified name is unique to this entity. */ + def qualifiedName: String + + /** The template of which this entity is a member. */ def inTemplate: TemplateEntity + + /** The list of entities such that each is a member of the entity that follows it; the first entity is always this + * entity, the last the root package entity. */ def toRoot: List[Entity] - def qualifiedName: String + + /** The qualified name of this entity. */ override def toString = qualifiedName + + /** The Scaladoc universe of which this entity is a member. */ def universe: Universe + + /** The annotations attached to this entity, if any. */ def annotations: List[Annotation] + } -/** A class, trait, object or package. A package is represented as an instance - * of the `Package` subclass. A class, trait, object or package may be - * directly an instance of `WeakTemplateEntity` if it is not ''documentable'' - * (that is, if there is no documentation page for it in the current site), - * otherwise, it will be represented as an instance of the `TemplateEntity` - * subclass. */ + +/** A template, which is either a class, trait, object or package. Depending on whether documentation is available + * or not, the template will be modeled as a [scala.tools.nsc.doc.model.NoDocTemplate] or a + * [scala.tools.nsc.doc.model.DocTemplateEntity]. */ trait TemplateEntity extends Entity { + + /** Whether this template is a package (including the root package). */ def isPackage: Boolean + + /** Whether this template is the root package. */ def isRootPackage: Boolean + + /** Whether this template is a trait. */ def isTrait: Boolean + + /** Whether this template is a class. */ def isClass: Boolean + + /** Whether this template is an object. */ def isObject: Boolean + + /** Whether documentation is available for this template. */ def isDocTemplate: Boolean + + /** Whether this template is a case class. */ def isCaseClass: Boolean + + /** The self-type of this template, if it differs from the template type. */ def selfType : Option[TypeEntity] + } -trait NoDocTemplate extends TemplateEntity -/** A member of a class, trait, object or package. */ + +/** An entity that is a member of a template. All entities, including templates, are member of another entity + * except for parameters and annotations. Note that all members of a template are modelled, including those that are + * inherited and not declared locally. */ trait MemberEntity extends Entity { + + /** The comment attached to this member, if any. */ def comment: Option[Comment] + + /** The template of which this entity is a member. */ def inTemplate: DocTemplateEntity + + /** The list of entities such that each is a member of the entity that follows it; the first entity is always this + * member, the last the root package entity. */ def toRoot: List[MemberEntity] + + /** The templates in which this member has been declared. The first element of the list is the template that contains + * the currently active declaration of this member, subsequent elements are declarations that have been overriden. If + * the first element is equal to `inTemplate`, the member is declared locally, if not, it has been inherited. All + * elements of this list are in the linearization of `inTemplate`. */ def inDefinitionTemplates: List[TemplateEntity] + + /** The qualified name of the member in its currently active declaration template. */ def definitionName: String + + /** The visibility of this member. Note that members with restricted visibility may not be modeled in some + * universes. */ def visibility: Visibility + + /** The flags that have been set for this entity. The following flags are supported: `implicit`, `sealed`, `abstract`, + * and `final`. */ def flags: List[Paragraph] + + /** Some deprecation message if this member is deprecated, or none otherwise. */ def deprecation: Option[Body] + + @deprecated("Use `inDefinitionTemplates` instead") def inheritedFrom: List[TemplateEntity] + + /** For members representing values: the type of the value returned by this member; for members + * representing types: the type itself. */ def resultType: TypeEntity + + /** Whether this member is a method. */ def isDef: Boolean + + /** Whether this member is a value (this excludes lazy values). */ def isVal: Boolean + + /** Whether this member is a lazy value. */ def isLazyVal: Boolean + + /** Whether this member is a variable. */ def isVar: Boolean - def isImplicit: Boolean - def isAbstract: Boolean + + /** Whether this member is a constructor. */ def isConstructor: Boolean + + /** Whether this member is an alias type. */ def isAliasType: Boolean + + /** Whether this member is an abstract type. */ def isAbstractType: Boolean + + /** Whether this member is a template. */ def isTemplate: Boolean + + /** Whether this member is implicit. */ + def isImplicit: Boolean + + /** Whether this member is abtract. */ + def isAbstract: Boolean + } + +/** An entity that is parameterized by types */ trait HigherKinded extends Entity { + + /** The type parameters of this entity. */ def typeParams: List[TypeParam] + } -/** A ''documentable'' class, trait or object (that is, a documentation page - * will be generated for it in the current site). */ + +/** A template (class, trait, object or package) which is referenced in the universe, but for which no further + * documentation is available. Only templates for which a source file is given are documented by Scaladoc. */ +trait NoDocTemplate extends TemplateEntity + + +/** A template (class, trait, object or package) for which documentation is available. Only templates for which + * a source file is given are documented by Scaladoc. */ trait DocTemplateEntity extends TemplateEntity with MemberEntity { + + /** The list of templates such that each is a member of the template that follows it; the first template is always + * this template, the last the root package entity. */ def toRoot: List[DocTemplateEntity] + + /** The source file in which the current template is defined and the line where the definition starts, if they exist. + * A source file exists for all templates, except for those that are generated synthetically by Scaladoc. */ def inSource: Option[(io.AbstractFile, Int)] + + /** An HTTP address at which the source of this template is available, if it is available. An address is available + * only if the `docsourceurl` setting has been set. */ def sourceUrl: Option[java.net.URL] + + /** The direct super-type of this template. */ def parentType: Option[TypeEntity] + + @deprecated("Use `linearizationTemplates` and `linearizationTypes` instead") def linearization: List[(TemplateEntity, TypeEntity)] + + /** All class, trait and object templates which are part of this template's linearization, in lineratization order. + * This template's linearization contains all of its direct and indirect super-classes and super-traits. */ def linearizationTemplates: List[TemplateEntity] + + /** All instantiated types which are part of this template's linearization, in lineratization order. + * This template's linearization contains all of its direct and indirect super-types. */ def linearizationTypes: List[TypeEntity] + + /**All class, trait and object templates for which this template is a direct or indirect super-class or super-trait. + * Only templates for which documentation is available in the universe (`DocTemplateEntity`) are listed. */ def subClasses: List[DocTemplateEntity] + + /** All members of this template. If this template is a package, only templates for which documentation is available + * in the universe (`DocTemplateEntity`) are listed. */ def members: List[MemberEntity] + + /** All templates that are members of this template. If this template is a package, only templates for which + * documentation is available in the universe (`DocTemplateEntity`) are listed. */ def templates: List[DocTemplateEntity] + + /** All methods that are members of this template. */ def methods: List[Def] + + /** All values, lazy values and variables that are members of this template. */ def values: List[Val] + + /** All abstract types that are members of this template. */ def abstractTypes: List[AbstractType] + + /** All type aliases that are members of this template. */ def aliasTypes: List[AliasType] + + /** The companion of this template, or none. If a class and an object are defined as a pair of the same name, the + * other entity of the pair is the companion. */ def companion: Option[DocTemplateEntity] + } -/** A ''documentable'' trait. */ + +/** A trait template. */ trait Trait extends DocTemplateEntity with HigherKinded -/** A ''documentable'' class. */ + +/** A class template. */ trait Class extends Trait with HigherKinded { + + /** The primary constructor of this class, if it has been defined. */ def primaryConstructor: Option[Constructor] + + /** All constructors of this class, including the primary constructor. */ def constructors: List[Constructor] + + /** The value parameters of this case class, or an empty list if this class is not a case class. As case class value + * paramters cannot be curried, the outer list has exactly one element. */ def valueParams: List[List[ValueParam]] + } -/** A ''documentable'' object. */ + +/** An object template. */ trait Object extends DocTemplateEntity -/** A package that contains at least one ''documentable'' class, trait, - * object or package. */ + +/** A package template. A package is in the universe if it is declared as a package object, or if it + * contains at least one template. */ trait Package extends Object { + + /** The package of which this package is a member. */ def inTemplate: Package + + /** The package such that each is a member of the package that follows it; the first package is always this + * package, the last the root package. */ def toRoot: List[Package] + + /** All packages that are member of this package. */ def packages: List[Package] } -/** A package represent the root of Entities hierarchy */ + +/** The root package, which contains directly or indirectly all members in the universe. A universe + * contains exactly one root package. */ trait RootPackage extends Package + +/** A non-template member (method, value, lazy value, variable, constructor, alias type, and abstract type). */ trait NonTemplateMemberEntity extends MemberEntity { + + /** Whether this member is a use case. A use case is a member which does not exist in the documented code. + * It corresponds to a real member, and provides a simplified, yet compatible signature for that member. */ def isUseCase: Boolean + } -/** A method (`def`) of a ''documentable'' class, trait or object. */ + +/** A method (`def`) of a template. */ trait Def extends NonTemplateMemberEntity with HigherKinded { + + /** The value parameters of this method. Each parameter block of a curried method is an element of the list. + * Each parameter block is a list of value parameters. */ def valueParams : List[List[ValueParam]] + } + +/** A constructor of a class. */ trait Constructor extends NonTemplateMemberEntity { + + /** Whether this is the primary constructor of a class. The primary constructor is defined syntactically as part of + * the declaration of the class. */ def isPrimary: Boolean + + /** The value parameters of this constructor. As constructors cannot be curried, the outer list has exactly one + * element. */ def valueParams : List[List[ValueParam]] + } -/** A value (`val`), lazy val (`lazy val`) or variable (`var`) of a - * ''documentable'' class, trait or object. */ + +/** A value (`val`), lazy val (`lazy val`) or variable (`var`) of a template. */ trait Val extends NonTemplateMemberEntity -/** An abstract type of a ''documentable'' class, trait or object. */ + +/** An abstract type member of a template. */ trait AbstractType extends NonTemplateMemberEntity with HigherKinded { + + /** The lower bound for this abstract type, if it has been defined. */ def lo: Option[TypeEntity] + + /** The upper bound for this abstract type, if it has been defined. */ def hi: Option[TypeEntity] + } -/** An abstract type of a ''documentable'' class, trait or object. */ + +/** An type alias of a template. */ trait AliasType extends NonTemplateMemberEntity with HigherKinded { + + /** The type aliased by this type alias. */ def alias: TypeEntity + } + +/** A parameter to an entity. */ trait ParameterEntity extends Entity { + + /** Whether this parameter is a type parameter. */ def isTypeParam: Boolean + + /** Whether this parameter is a value parameter. */ def isValueParam: Boolean + } -/** A type parameter to a class or trait or to a method. */ + +/** A type parameter to a class, trait, or method. */ trait TypeParam extends ParameterEntity with HigherKinded { + + /** The variance of this type type parameter. Valid values are "+", "-", and the empty string. */ def variance: String + + /** The lower bound for this type parameter, if it has been defined. */ def lo: Option[TypeEntity] + + /** The upper bound for this type parameter, if it has been defined. */ def hi: Option[TypeEntity] + } -/** A value parameter to a constructor or to a method. */ + +/** A value parameter to a constructor or method. */ trait ValueParam extends ParameterEntity { + + /** The type of this value parameter. */ def resultType: TypeEntity - def defaultValue: Option[TreeEntity] - def isImplicit: Boolean -} -/** An annotation, defined by its class and its constructor arguments. */ -trait Annotation extends Entity { - def annotationClass: TemplateEntity - def arguments: List[ValueArgument] -} + /** The devault value of this value parameter, if it has been defined. */ + def defaultValue: Option[TreeEntity] -/** A value that is passed as an argument to a value paramater. */ -trait ValueArgument { - def parameter: Option[ValueParam] - def value: TreeEntity -} + /** Whether this value parameter is implicit. */ + def isImplicit: Boolean -/** An type that represents visibility of members. */ -sealed trait Visibility { - def isProtected: Boolean = false - def isPublic: Boolean = false } -/** The visibility of `private[this]` members. */ -case class PrivateInInstance() extends Visibility -/** The visibility of `protected[this]` members. */ -case class ProtectedInInstance() extends Visibility { - override def isProtected = true -} +/** An annotation to an entity. */ +trait Annotation extends Entity { -/** The visibility of `private[owner]` members. An unqualified private members - * is encoded with `owner` equal to the members's `inTemplate`. */ -case class PrivateInTemplate(owner: TemplateEntity) extends Visibility + /** The class of this annotation. */ + def annotationClass: TemplateEntity -/** The visibility of `protected[owner]` members. An unqualified protected - * members is encoded with `owner` equal to the members's `inTemplate`. - * Note that whilst the member is visible in any template owned by `owner`, - * it is only visible in subclasses of the member's `inTemplate`. */ -case class ProtectedInTemplate(owner: TemplateEntity) extends Visibility { - override def isProtected = true -} + /** The arguments passed to the constructor of the annotation class. */ + def arguments: List[ValueArgument] -/** The visibility of public members. */ -case class Public() extends Visibility { - override def isPublic = true } diff --git a/src/compiler/scala/tools/nsc/doc/model/TreeEntity.scala b/src/compiler/scala/tools/nsc/doc/model/TreeEntity.scala index 98407ff58a..23a4e17a9a 100644 --- a/src/compiler/scala/tools/nsc/doc/model/TreeEntity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/TreeEntity.scala @@ -1,16 +1,27 @@ - - - -/** we create a TreeEntity to store some text and some hyperLinks to make on entities in it */ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author Chris James + */ package scala.tools.nsc package doc package model -import scala.collection.immutable.TreeMap +import scala.collection._ + + +/** A fragment of code. */ +abstract class TreeEntity { + + /** The human-readable representation of this abstract syntax tree. */ + def expression: String + + /** Maps which parts of this syntax tree's name reference entities. The map is indexed by the position of the first + * character that reference some entity, and contains the entity and the position of the last referenced + * character. The referenced character ranges do not to overlap or nest. The map is sorted by position. */ + def refEntity: SortedMap[Int, (Entity, Int)] + /** The human-readable representation of this abstract syntax tree. */ + override def toString = expression -class TreeEntity { - var expression:String = "?" - var refs = new TreeMap[Int, (Entity, Int)] // start, (Entity to be linked to , end) } diff --git a/src/compiler/scala/tools/nsc/doc/model/TreeFactory.scala b/src/compiler/scala/tools/nsc/doc/model/TreeFactory.scala index 63a1510ddc..5ed0aa740e 100755 --- a/src/compiler/scala/tools/nsc/doc/model/TreeFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/TreeFactory.scala @@ -2,6 +2,8 @@ package scala.tools.nsc package doc package model +import scala.collection._ + /** The goal of this trait is , using makeTree, * to browse a tree to * 1- have the String of the complete tree (tree.expression) @@ -11,32 +13,26 @@ package model * */ -trait TreeFactory { - thisTreeFactory: ModelFactory with TreeFactory => - val global: Global +trait TreeFactory { thisTreeFactory: ModelFactory with TreeFactory => + val global: Global import global._ def makeTree(rhs: Tree): TreeEntity = { - val printSteps: Boolean = false - val tree = new TreeEntity + var expr: String = null + var refs = new immutable.TreeMap[Int, (Entity, Int)] // start, (Entity to be linked to , end) try { val firstIndex = rhs.pos.startOrPoint /** Gets the full string of the right hand side of a parameter, without links */ - def makeExpression(rhs: Tree){ - val start = rhs.pos.startOrPoint - val end = rhs.pos.endOrPoint - var expr = "" - for (i <- start until end) expr += rhs.pos.source.content.apply(i) - rhs match { - case Block(r,s) => expr += "}" - case _ => - } - tree.expression += expr + for (i <- firstIndex until rhs.pos.endOrPoint) + expr += rhs.pos.source.content.apply(i) + rhs match { + case Block(r,s) => expr += "}" + case _ => } val traverser = new Traverser { @@ -51,7 +47,7 @@ trait TreeFactory { var asym = rhs.symbol if (asym.isClass) makeTemplate(asym) match{ case docTmpl: DocTemplateImpl => - tree.refs += ((start,(docTmpl,end))) + refs += ((start, (docTmpl,end))) case _ => } else if (asym.isTerm && asym.owner.isClass){ @@ -60,7 +56,7 @@ trait TreeFactory { case docTmpl: DocTemplateImpl => val mbrs: List[MemberImpl] = makeMember(asym,docTmpl) mbrs foreach {mbr => - tree.refs += ((start,(mbr,end))) + refs += ((start, (mbr,end))) } case _ => } @@ -87,16 +83,27 @@ trait TreeFactory { } - makeExpression(rhs) traverser.traverse(rhs) + + assert(expr != null, "No expression constructed for rhs=" + rhs.toString) + new TreeEntity { + val expression = expr + val refEntity = refs + } + } + catch { case e: Throwable => //println("Bad tree: " + rhs) + // TODO: This exception should be rethrown and no dummy tree entity should be created. + new TreeEntity { + val expression = "?" + val refEntity = new immutable.TreeMap[Int, (Entity, Int)] + } + //throw e } - tree - } } diff --git a/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala b/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala index 79ff5e2899..67e955f613 100644 --- a/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala @@ -9,17 +9,21 @@ package model import scala.collection._ + +/** A type. Note that types and templates contain the same information only for the simplest types. For example, a type + * defines how a template's type parameters are instantiated (as in `List[Cow]`), what the template's prefix is + * (as in `johnsFarm.Cow`), and supports compound or structural types. */ abstract class TypeEntity { - /** A string representation of this type. */ + /** The human-readable representation of this type. */ def name: String - /** Maps which parts of this type's name reference other entities. The map is indexed by the position of the first + /** Maps which parts of this type's name reference entities. The map is indexed by the position of the first * character that reference some entity, and contains the entity and the position of the last referenced * character. The referenced character ranges do not to overlap or nest. The map is sorted by position. */ def refEntity: SortedMap[Int, (TemplateEntity, Int)] - override def toString = - name + /** The human-readable representation of this type. */ + override def toString = name } diff --git a/src/compiler/scala/tools/nsc/doc/model/ValueArgument.scala b/src/compiler/scala/tools/nsc/doc/model/ValueArgument.scala new file mode 100644 index 0000000000..781ff113fb --- /dev/null +++ b/src/compiler/scala/tools/nsc/doc/model/ValueArgument.scala @@ -0,0 +1,20 @@ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author Gilles Dubochet + */ + +package scala.tools.nsc +package doc +package model + + +/** A value that is passed as an argument to a value parameter. */ +trait ValueArgument { + + /** The parameter as argument to which this value is passed, if it is known. */ + def parameter: Option[ValueParam] + + /** The expression that calculates the value. */ + def value: TreeEntity + +} diff --git a/src/compiler/scala/tools/nsc/doc/model/Visibility.scala b/src/compiler/scala/tools/nsc/doc/model/Visibility.scala new file mode 100644 index 0000000000..657d34ee54 --- /dev/null +++ b/src/compiler/scala/tools/nsc/doc/model/Visibility.scala @@ -0,0 +1,39 @@ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author Gilles Dubochet + */ + +package scala.tools.nsc +package doc +package model + +/** An type that represents visibility of members. */ +sealed trait Visibility { + def isProtected: Boolean = false + def isPublic: Boolean = false +} + +/** The visibility of `private[this]` members. */ +case class PrivateInInstance() extends Visibility + +/** The visibility of `protected[this]` members. */ +case class ProtectedInInstance() extends Visibility { + override def isProtected = true +} + +/** The visibility of `private[owner]` members. An unqualified private members + * is encoded with `owner` equal to the members's `inTemplate`. */ +case class PrivateInTemplate(owner: TemplateEntity) extends Visibility + +/** The visibility of `protected[owner]` members. An unqualified protected + * members is encoded with `owner` equal to the members's `inTemplate`. + * Note that whilst the member is visible in any template owned by `owner`, + * it is only visible in subclasses of the member's `inTemplate`. */ +case class ProtectedInTemplate(owner: TemplateEntity) extends Visibility { + override def isProtected = true +} + +/** The visibility of public members. */ +case class Public() extends Visibility { + override def isPublic = true +} -- cgit v1.2.3