[scaladoc] Fully commented the Scaladoc model.

7 files changed, 366 insertions, 101 deletions

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
+}