From f881249ba19084b194c0db07fd36ab2a68af5228 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Thu, 12 Jul 2012 14:08:34 +0200 Subject: Scaladoc: Inherited templates in diagrams Related to SI-3314, where we started showing inherited templates that were normally not documented. This patch corrects a problem in parentTypes that was preventing inherited templates from being displayed in diagrams. Also renamed: PackageDiagram => ContentDiagram ClassDiagram => InheritanceDiagram which should have been done much earlier --- .../scala/tools/nsc/doc/html/page/Template.scala | 2 +- .../html/page/diagram/DotDiagramGenerator.scala | 12 ++-- .../scala/tools/nsc/doc/model/ModelFactory.scala | 22 +++++- .../tools/nsc/doc/model/diagram/Diagram.scala | 16 ++--- .../nsc/doc/model/diagram/DiagramFactory.scala | 16 ++--- test/scaladoc/resources/SI-3314-diagrams.scala | 78 ++++++++++++++++++++++ test/scaladoc/run/SI-3314-diagrams.check | 1 + test/scaladoc/run/SI-3314-diagrams.scala | 37 ++++++++++ test/scaladoc/run/diagrams-base.scala | 6 +- 9 files changed, 163 insertions(+), 27 deletions(-) create mode 100644 test/scaladoc/resources/SI-3314-diagrams.scala create mode 100644 test/scaladoc/run/SI-3314-diagrams.check create mode 100644 test/scaladoc/run/SI-3314-diagrams.scala 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 47834e542c..bba838ddcf 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -769,7 +769,7 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp mbr match { case dte: DocTemplateEntity if !isSelf => -

{ inside(hasLinks = false, nameLink = relativeLinkTo(dte)) }

+

{ inside(hasLinks = true, nameLink = relativeLinkTo(dte)) }

case _ if isSelf =>

{ inside(hasLinks = true) }

case _ => diff --git a/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotDiagramGenerator.scala b/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotDiagramGenerator.scala index 8648fdb0a1..59560befc9 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotDiagramGenerator.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotDiagramGenerator.scala @@ -25,7 +25,7 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { // maps an index to its corresponding node private var index2Node: Map[Int, Node] = null // true if the current diagram is a class diagram - private var isClassDiagram = false + private var isInheritanceDiagram = false // incoming implicit nodes (needed for determining the CSS class of a node) private var incomingImplicitNodes: List[Node] = List() // the suffix used when there are two many classes to show @@ -66,10 +66,10 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { var superClasses = List[Node]() var incomingImplicits = List[Node]() var outgoingImplicits = List[Node]() - isClassDiagram = false + isInheritanceDiagram = false d match { - case ClassDiagram(_thisNode, _superClasses, _subClasses, _incomingImplicits, _outgoingImplicits) => + case InheritanceDiagram(_thisNode, _superClasses, _subClasses, _incomingImplicits, _outgoingImplicits) => def textTypeEntity(text: String) = new TypeEntity { @@ -108,7 +108,7 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { nodes = List() edges = (thisNode -> superClasses) :: subClasses.map(_ -> List(thisNode)) node2Index = (thisNode::subClasses:::superClasses:::incomingImplicits:::outgoingImplicits).zipWithIndex.toMap - isClassDiagram = true + isInheritanceDiagram = true incomingImplicitNodes = incomingImplicits case _ => nodes = d.nodes @@ -119,7 +119,7 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { index2Node = node2Index map {_.swap} val implicitsDot = { - if (!isClassDiagram) "" + if (!isInheritanceDiagram) "" else { // dot cluster containing thisNode val thisCluster = "subgraph clusterThis {\n" + @@ -360,7 +360,7 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { private def transform(e:scala.xml.Node): scala.xml.Node = e match { // add an id and class attribute to the SVG element case Elem(prefix, "svg", attribs, scope, child @ _*) => { - val klass = if (isClassDiagram) "class-diagram" else "package-diagram" + val klass = if (isInheritanceDiagram) "class-diagram" else "package-diagram" Elem(prefix, "svg", attribs, scope, child map(x => transform(x)) : _*) % new UnprefixedAttribute("id", "graph" + counter, Null) % new UnprefixedAttribute("class", klass, Null) diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 2efbfbe43c..61b4267f3c 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -858,8 +858,28 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { parents else parents.filterNot((p: Type) => ignoreParents(p.typeSymbol)) + + /** Returns: + * - a DocTemplate if the type's symbol is documented + * - a NoDocTemplateMember if the type's symbol is not documented in its parent but in another template + * - a NoDocTemplate if the type's symbol is not documented at all */ + def makeTemplateOrMemberTemplate(parent: Type): TemplateImpl = { + def noDocTemplate = makeTemplate(parent.typeSymbol) + findTemplateMaybe(parent.typeSymbol) match { + case Some(tpl) => tpl + case None => parent match { + case TypeRef(pre, sym, args) => + findTemplateMaybe(pre.typeSymbol) match { + case Some(tpl) => findMember(parent.typeSymbol, tpl).collect({case t: TemplateImpl => t}).getOrElse(noDocTemplate) + case None => noDocTemplate + } + case _ => noDocTemplate + } + } + } + filtParents.map(parent => { - val templateEntity = makeTemplate(parent.typeSymbol) + val templateEntity = makeTemplateOrMemberTemplate(parent) val typeEntity = makeType(parent, inTpl) (templateEntity, typeEntity) }) diff --git a/src/compiler/scala/tools/nsc/doc/model/diagram/Diagram.scala b/src/compiler/scala/tools/nsc/doc/model/diagram/Diagram.scala index 8527ca4039..2b804ca10f 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/Diagram.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/Diagram.scala @@ -13,18 +13,18 @@ import model._ abstract class Diagram { def nodes: List[Node] def edges: List[(Node, List[Node])] - def isPackageDiagram = false - def isClassDiagram = false + def isContentDiagram = false // Implemented by ContentDiagram + def isInheritanceDiagram = false // Implemented by InheritanceDiagram def depthInfo: DepthInfo } -case class PackageDiagram(nodes:List[/*Class*/Node], edges:List[(Node, List[Node])]) extends Diagram { - override def isPackageDiagram = true - lazy val depthInfo = new PackageDiagramDepth(this) +case class ContentDiagram(nodes:List[/*Class*/Node], edges:List[(Node, List[Node])]) extends Diagram { + override def isContentDiagram = true + lazy val depthInfo = new ContentDiagramDepth(this) } /** A class diagram */ -case class ClassDiagram(thisNode: ThisNode, +case class InheritanceDiagram(thisNode: ThisNode, superClasses: List[/*Class*/Node], subClasses: List[/*Class*/Node], incomingImplicits: List[ImplicitNode], @@ -33,7 +33,7 @@ case class ClassDiagram(thisNode: ThisNode, def edges = (thisNode -> (superClasses ::: outgoingImplicits)) :: (subClasses ::: incomingImplicits).map(_ -> List(thisNode)) - override def isClassDiagram = true + override def isInheritanceDiagram = true lazy val depthInfo = new DepthInfo { def maxDepth = 3 def nodeDepth(node: Node) = @@ -115,7 +115,7 @@ case class OutsideNode(tpe: TypeEntity, tpl: Option[TemplateEntity], tooltip: Op // Computing and offering node depth information -class PackageDiagramDepth(pack: PackageDiagram) extends DepthInfo { +class ContentDiagramDepth(pack: ContentDiagram) extends DepthInfo { private[this] var _maxDepth = 0 private[this] var _nodeDepth = Map[Node, Int]() private[this] var seedNodes = Set[Node]() diff --git a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala index 4b05da98cd..731801b143 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala @@ -93,7 +93,7 @@ trait DiagramFactory extends DiagramDirectiveParser { val filteredImplicitOutgoingNodes = if (diagramFilter.hideOutgoingImplicits) Nil else outgoingImplicitNodes // final diagram filter - filterDiagram(ClassDiagram(thisNode, filteredSuperclasses.reverse, filteredSubclasses.reverse, filteredIncomingImplicits, filteredImplicitOutgoingNodes), diagramFilter) + filterDiagram(InheritanceDiagram(thisNode, filteredSuperclasses.reverse, filteredSubclasses.reverse, filteredIncomingImplicits, filteredImplicitOutgoingNodes), diagramFilter) } tModel += System.currentTimeMillis @@ -173,9 +173,9 @@ trait DiagramFactory extends DiagramDirectiveParser { val anyRefSubtypes = Nil val allAnyRefTypes = aggregationNode("All AnyRef subtypes") val nullTemplate = makeTemplate(NullClass) - PackageDiagram(allAnyRefTypes::nodes, (mapNodes(nullTemplate), allAnyRefTypes::anyRefSubtypes)::edges.filterNot(_._1.tpl == Some(nullTemplate))) + ContentDiagram(allAnyRefTypes::nodes, (mapNodes(nullTemplate), allAnyRefTypes::anyRefSubtypes)::edges.filterNot(_._1.tpl == Some(nullTemplate))) } else - PackageDiagram(nodes, edges) + ContentDiagram(nodes, edges) filterDiagram(diagram, diagramFilter) } @@ -200,10 +200,10 @@ trait DiagramFactory extends DiagramDirectiveParser { else { // Final diagram, with the filtered nodes and edges diagram match { - case ClassDiagram(thisNode, _, _, _, _) if diagramFilter.hideNode(thisNode) => + case InheritanceDiagram(thisNode, _, _, _, _) if diagramFilter.hideNode(thisNode) => None - case ClassDiagram(thisNode, superClasses, subClasses, incomingImplicits, outgoingImplicits) => + case InheritanceDiagram(thisNode, superClasses, subClasses, incomingImplicits, outgoingImplicits) => def hideIncoming(node: Node): Boolean = diagramFilter.hideNode(node) || diagramFilter.hideEdge(node, thisNode) @@ -214,13 +214,13 @@ trait DiagramFactory extends DiagramDirectiveParser { // println(thisNode) // println(superClasses.map(cl => "super: " + cl + " " + hideOutgoing(cl)).mkString("\n")) // println(subClasses.map(cl => "sub: " + cl + " " + hideIncoming(cl)).mkString("\n")) - Some(ClassDiagram(thisNode, + Some(InheritanceDiagram(thisNode, superClasses.filterNot(hideOutgoing(_)), subClasses.filterNot(hideIncoming(_)), incomingImplicits.filterNot(hideIncoming(_)), outgoingImplicits.filterNot(hideOutgoing(_)))) - case PackageDiagram(nodes0, edges0) => + case ContentDiagram(nodes0, edges0) => // Filter out all edges that: // (1) are sources of hidden classes // (2) are manually hidden by the user @@ -242,7 +242,7 @@ trait DiagramFactory extends DiagramDirectiveParser { val sourceNodes = edges.map(_._1) val sinkNodes = edges.map(_._2).flatten val nodes = (sourceNodes ::: sinkNodes).distinct - Some(PackageDiagram(nodes, edges)) + Some(ContentDiagram(nodes, edges)) } } diff --git a/test/scaladoc/resources/SI-3314-diagrams.scala b/test/scaladoc/resources/SI-3314-diagrams.scala new file mode 100644 index 0000000000..b80a97b522 --- /dev/null +++ b/test/scaladoc/resources/SI-3314-diagrams.scala @@ -0,0 +1,78 @@ +package scala.test.scaladoc { + + /** Check the interaction between SI-3314 and diagrams + * - the three enumerations below should get valid content diagrams: + * Value + * __________/|\__________ + * / / / | \ \ \ + * Mon Tue Wed Thu Fri Sat Sun + * + * - each member should receive an inhertiance diagram: + * Value + * | + * | + * {Mon,Tue,Wed,Thu,Fri,Sat,Sun} + */ + package diagrams { + + /** @contentDiagram + * @inheritanceDiagram hideDiagram */ + trait WeekDayTraitWithDiagram extends Enumeration { + type WeekDay = Value + /** @inheritanceDiagram */ + object Mon extends WeekDay + /** @inheritanceDiagram */ + object Tue extends WeekDay + /** @inheritanceDiagram */ + object Wed extends WeekDay + /** @inheritanceDiagram */ + object Thu extends WeekDay + /** @inheritanceDiagram */ + object Fri extends WeekDay + /** @inheritanceDiagram */ + object Sat extends WeekDay + /** @inheritanceDiagram */ + object Sun extends WeekDay + } + + /** @contentDiagram + * @inheritanceDiagram hideDiagram */ + class WeekDayClassWithDiagram extends Enumeration { + type WeekDay = Value + /** @inheritanceDiagram */ + object Mon extends WeekDay + /** @inheritanceDiagram */ + object Tue extends WeekDay + /** @inheritanceDiagram */ + object Wed extends WeekDay + /** @inheritanceDiagram */ + object Thu extends WeekDay + /** @inheritanceDiagram */ + object Fri extends WeekDay + /** @inheritanceDiagram */ + object Sat extends WeekDay + /** @inheritanceDiagram */ + object Sun extends WeekDay + } + + /** @contentDiagram + * @inheritanceDiagram hideDiagram */ + object WeekDayObjectWithDiagram extends Enumeration { + type WeekDay = Value + /** @inheritanceDiagram */ + object Mon extends WeekDay + /** @inheritanceDiagram */ + object Tue extends WeekDay + /** @inheritanceDiagram */ + object Wed extends WeekDay + /** @inheritanceDiagram */ + object Thu extends WeekDay + /** @inheritanceDiagram */ + object Fri extends WeekDay + /** @inheritanceDiagram */ + object Sat extends WeekDay + /** @inheritanceDiagram */ + object Sun extends WeekDay + } + } +} \ No newline at end of file diff --git a/test/scaladoc/run/SI-3314-diagrams.check b/test/scaladoc/run/SI-3314-diagrams.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-3314-diagrams.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-3314-diagrams.scala b/test/scaladoc/run/SI-3314-diagrams.scala new file mode 100644 index 0000000000..0b07e4c5bd --- /dev/null +++ b/test/scaladoc/run/SI-3314-diagrams.scala @@ -0,0 +1,37 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.nsc.doc.model.diagram._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def resourceFile = "SI-3314-diagrams.scala" + + // no need for special settings + def scaladocSettings = "-diagrams" + + def testModel(rootPackage: Package) = { + // get the quick access implicit defs in scope (_package(s), _class(es), _trait(s), object(s) _method(s), _value(s)) + import access._ + + // just need to check the member exists, access methods will throw an error if there's a problem + val base = rootPackage._package("scala")._package("test")._package("scaladoc") + + val diagrams = base._package("diagrams") + def testDiagram(doc: DocTemplateEntity, diag: Option[Diagram], nodes: Int, edges: Int) = { + assert(diag.isDefined, doc.qualifiedName + " diagram missing") + assert(diag.get.nodes.length == nodes, + doc.qualifiedName + "'s diagram: node count " + diag.get.nodes.length + " == " + nodes) + assert(diag.get.edges.length == edges, + doc.qualifiedName + "'s diagram: edge count " + diag.get.edges.length + " == " + edges) + } + + val templates = List(diagrams._trait("WeekDayTraitWithDiagram"), diagrams._class("WeekDayClassWithDiagram"), diagrams._object("WeekDayObjectWithDiagram")) + + for (template <- templates) { + testDiagram(template, template.contentDiagram, 8, 7) + val subtemplates = List("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun").map(template._object(_)) + for (subtemplate <- subtemplates) + testDiagram(subtemplate, subtemplate.inheritanceDiagram, 2, 1) + } + } +} \ No newline at end of file diff --git a/test/scaladoc/run/diagrams-base.scala b/test/scaladoc/run/diagrams-base.scala index 38bed06502..b7aeed51d2 100644 --- a/test/scaladoc/run/diagrams-base.scala +++ b/test/scaladoc/run/diagrams-base.scala @@ -42,7 +42,7 @@ object Test extends ScaladocModelTest { assert(diag.nodes.filter(_.isThisNode).length == 1) // 1. check class E diagram - assert(diag.isClassDiagram) + assert(diag.isInheritanceDiagram) val (incoming, outgoing) = diag.edges.partition(!_._1.isThisNode) assert(incoming.length == 5) @@ -56,14 +56,14 @@ object Test extends ScaladocModelTest { assert(incomingSubclass.length == 2) assert(incomingImplicit.length == 3) - val classDiag = diag.asInstanceOf[ClassDiagram] + val classDiag = diag.asInstanceOf[InheritanceDiagram] assert(classDiag.incomingImplicits.length == 3) assert(classDiag.outgoingImplicits.length == 1) // 2. check package diagram // NOTE: Z should be eliminated because it's isolated val packDiag = base.contentDiagram.get - assert(packDiag.isPackageDiagram) + assert(packDiag.isContentDiagram) assert(packDiag.nodes.length == 8) // check singular object removal assert(packDiag.edges.length == 4) assert(packDiag.edges.foldLeft(0)(_ + _._2.length) == 6) -- cgit v1.2.3