From fcbdc1725c6fcd65a071709408ef75097f487cb7 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Thu, 28 Jun 2012 15:54:08 +0200 Subject: SI-5235 Correct usecase variable expansion The bug is related to a couple of other annoyances, also fixed: - usecases without type params were crashing scaladoc due to a change in the PolyTypes class (not allowing empty tparams list) - properly getting rid of backticks (even if the link is not valid) - correct linking for usecases with $Coll = `immutable.Seq` (the symbol searching algorithm was too of restrictive, now we search the entire ownerchain - and the empty package at the end) - give a warning if the type lookup fails - finally, added a $Coll variable to List, for some reason it wasn't there and we were getting immutable.Seq as the result of use cases. --- src/compiler/scala/tools/nsc/ast/DocComments.scala | 49 ++++++++++++++-------- .../scala/tools/nsc/typechecker/Typers.scala | 5 ++- src/library/scala/collection/immutable/List.scala | 3 +- .../scala/collection/immutable/StringOps.scala | 2 +- .../scala/collection/mutable/ArrayOps.scala | 2 +- .../scala/tools/partest/ScaladocModelTest.scala | 10 +++++ 6 files changed, 49 insertions(+), 22 deletions(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/ast/DocComments.scala b/src/compiler/scala/tools/nsc/ast/DocComments.scala index b545140c4a..b2d6800ebb 100755 --- a/src/compiler/scala/tools/nsc/ast/DocComments.scala +++ b/src/compiler/scala/tools/nsc/ast/DocComments.scala @@ -457,22 +457,16 @@ trait DocComments { self: Global => case List() => NoType case site :: sites1 => select(site.thisType, name, findIn(sites1)) } - val (classes, pkgs) = site.ownerChain.span(!_.isPackageClass) - findIn(classes ::: List(pkgs.head, rootMirror.RootClass)) + // Previously, searching was taking place *only* in the current package and in the root package + // now we're looking for it everywhere in the hierarchy, so we'll be able to link variable expansions like + // immutable.Seq in package immutable + //val (classes, pkgs) = site.ownerChain.span(!_.isPackageClass) + //val sites = (classes ::: List(pkgs.head, rootMirror.RootClass))) + //findIn(sites) + findIn(site.ownerChain ::: List(definitions.EmptyPackage)) } - def getType(_str: String, variable: String): Type = { - /* - * work around the backticks issue suggested by Simon in - * https://groups.google.com/forum/?hl=en&fromgroups#!topic/scala-internals/z7s1CCRCz74 - * ideally, we'd have a removeWikiSyntax method in the CommentFactory to completely eliminate the wiki markup - */ - val str = - if (_str.length >= 2 && _str.startsWith("`") && _str.endsWith("`")) - _str.substring(1, _str.length - 2) - else - _str - + def getType(str: String, variable: String): Type = { def getParts(start: Int): List[String] = { val end = skipIdent(str, start) if (end == start) List() @@ -484,7 +478,7 @@ trait DocComments { self: Global => val parts = getParts(0) if (parts.isEmpty) { reporter.error(comment.codePos, "Incorrect variable expansion for " + variable + " in use case. Does the " + - "variable expand to wiki syntax when documenting " + site + "?") + "variable expand to wiki syntax when documenting " + site + "?") return ErrorType } val partnames = (parts.init map newTermName) :+ newTypeName(parts.last) @@ -498,17 +492,36 @@ trait DocComments { self: Global => case _ => (getSite(partnames.head), partnames.tail) } - (start /: rest)(select(_, _, NoType)) + val result = (start /: rest)(select(_, _, NoType)) + if (result == NoType) + reporter.warning(comment.codePos, "Could not find the type " + variable + " points to while expanding it " + + "for the usecase signature of " + sym + " in " + site + "." + + "In this context, " + variable + " = \"" + str + "\".") + result + } + + /** + * work around the backticks issue suggested by Simon in + * https://groups.google.com/forum/?hl=en&fromgroups#!topic/scala-internals/z7s1CCRCz74 + * ideally, we'd have a removeWikiSyntax method in the CommentFactory to completely eliminate the wiki markup + */ + def cleanupVariable(str: String) = { + val tstr = str.trim + if (tstr.length >= 2 && tstr.startsWith("`") && tstr.endsWith("`")) + tstr.substring(1, tstr.length - 1) + else + tstr } val aliasExpansions: List[Type] = for (alias <- aliases) yield lookupVariable(alias.name.toString.substring(1), site) match { case Some(repl) => - val tpe = getType(repl.trim, alias.name.toString) + val repl2 = cleanupVariable(repl) + val tpe = getType(repl2, alias.name.toString) if (tpe != NoType) tpe else { - val alias1 = alias.cloneSymbol(rootMirror.RootClass, alias.rawflags, newTypeName(repl)) + val alias1 = alias.cloneSymbol(rootMirror.RootClass, alias.rawflags, newTypeName(repl2)) typeRef(NoPrefix, alias1, Nil) } case None => diff --git a/src/compiler/scala/tools/nsc/typechecker/Typers.scala b/src/compiler/scala/tools/nsc/typechecker/Typers.scala index a570cd74d6..2d277603ee 100644 --- a/src/compiler/scala/tools/nsc/typechecker/Typers.scala +++ b/src/compiler/scala/tools/nsc/typechecker/Typers.scala @@ -1972,7 +1972,10 @@ trait Typers extends Modes with Adaptations with Tags { case SilentResultValue(tpt) => val alias = enclClass.newAliasType(name.toTypeName, useCase.pos) val tparams = cloneSymbolsAtOwner(tpt.tpe.typeSymbol.typeParams, alias) - alias setInfo typeFun(tparams, appliedType(tpt.tpe, tparams map (_.tpe))) + /* Unless we treat no-tparams usecases differently they blow up in typeFun + * def typeFun = PolyType(tparams, tpe) // <- which asserts (!tparams.isEmpty) */ + val newInfo = if (tparams.isEmpty) tpt.tpe else typeFun(tparams, appliedType(tpt.tpe, tparams map (_.tpe))) + alias setInfo newInfo context.scope.enter(alias) case _ => } diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala index 6fd8d143ee..74dc385f99 100644 --- a/src/library/scala/collection/immutable/List.scala +++ b/src/library/scala/collection/immutable/List.scala @@ -62,6 +62,7 @@ import java.io._ * section on `Lists` for more information. * * @define coll list + * @define Coll `List` * @define thatinfo the class of the returned collection. In the standard library configuration, * `That` is always `List[B]` because an implicit of type `CanBuildFrom[List, B, That]` * is defined in object `List`. @@ -96,7 +97,7 @@ sealed abstract class List[+A] extends AbstractSeq[A] * * @usecase def ::(x: A): List[A] * @inheritdoc - * + * * Example: * {{{1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)}}} */ diff --git a/src/library/scala/collection/immutable/StringOps.scala b/src/library/scala/collection/immutable/StringOps.scala index 633821ecea..7e60cc7195 100644 --- a/src/library/scala/collection/immutable/StringOps.scala +++ b/src/library/scala/collection/immutable/StringOps.scala @@ -25,7 +25,7 @@ import mutable.StringBuilder * @param repr the actual representation of this string operations object. * * @since 2.8 - * @define Coll `StringOps` + * @define Coll `String` * @define coll string */ final class StringOps(override val repr: String) extends AnyVal with StringLike[String] { diff --git a/src/library/scala/collection/mutable/ArrayOps.scala b/src/library/scala/collection/mutable/ArrayOps.scala index 7a595f211d..21c2aaaec7 100644 --- a/src/library/scala/collection/mutable/ArrayOps.scala +++ b/src/library/scala/collection/mutable/ArrayOps.scala @@ -30,7 +30,7 @@ import parallel.mutable.ParArray * * @tparam T type of the elements contained in this array. * - * @define Coll `ArrayOps` + * @define Coll `Array` * @define orderDependent * @define orderDependentFold * @define mayNotTerminateInf diff --git a/src/partest/scala/tools/partest/ScaladocModelTest.scala b/src/partest/scala/tools/partest/ScaladocModelTest.scala index de5354d4a0..be70a91e14 100644 --- a/src/partest/scala/tools/partest/ScaladocModelTest.scala +++ b/src/partest/scala/tools/partest/ScaladocModelTest.scala @@ -12,6 +12,7 @@ import scala.tools.nsc.util.CommandLineParser import scala.tools.nsc.doc.{Settings, DocFactory, Universe} import scala.tools.nsc.doc.model._ import scala.tools.nsc.reporters.ConsoleReporter +import scala.tools.nsc.doc.model.comment.Comment /** A class for testing scaladoc model generation * - you need to specify the code in the `code` method @@ -142,5 +143,14 @@ abstract class ScaladocModelTest extends DirectTest { case _ => sys.error("Error getting " + expl + ": " + list.length + " elements with this name. " + "All elements in list: [" + list.mkString(", ") + "]") } + + def extractCommentText(c: Comment) = { + def extractText(body: Any): String = body match { + case s: String => s + case p: Product => p.productIterator.toList.map(extractText(_)).mkString + case _ => "" + } + extractText(c.body) + } } } -- cgit v1.2.3 From f916434c119289773e5aad88c633c30f68a12e14 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Sat, 16 Jun 2012 04:23:43 +0200 Subject: SI-3314 SI-4888 Scaladoc: Relative type prefixes And adds support for linking to class members, only usable from the model factory now, so no links to members from the doc comment yet, sorry. But it fixes the Enumeration problem once and for all! Also corrected the inTpl for members obtained by implicit conversions, so they're in the correct template and the comment variable expansion is done from the correct (but different) template. Review by @kzys. --- .../scala/tools/nsc/doc/html/HtmlFactory.scala | 2 +- .../scala/tools/nsc/doc/html/HtmlPage.scala | 10 +- src/compiler/scala/tools/nsc/doc/html/Page.scala | 2 +- .../scala/tools/nsc/doc/html/page/Index.scala | 4 +- .../tools/nsc/doc/html/page/IndexScript.scala | 4 +- .../scala/tools/nsc/doc/html/page/Template.scala | 42 +----- .../html/page/diagram/DotDiagramGenerator.scala | 2 +- .../scala/tools/nsc/doc/model/Entity.scala | 17 ++- .../scala/tools/nsc/doc/model/ModelFactory.scala | 150 ++++++++++++++++----- .../doc/model/ModelFactoryImplicitSupport.scala | 27 ++-- .../scala/tools/nsc/doc/model/TypeEntity.scala | 5 +- .../nsc/doc/model/diagram/DiagramFactory.scala | 2 +- .../scala/tools/partest/ScaladocModelTest.scala | 26 +++- test/scaladoc/resources/SI-3314.scala | 70 ++++++++++ test/scaladoc/resources/SI_4676.scala | 4 - test/scaladoc/resources/Trac3484.scala | 27 ---- test/scaladoc/run/SI-3314.check | 1 + test/scaladoc/run/SI-3314.scala | 74 ++++++++++ test/scaladoc/run/SI-3484.check | 1 + test/scaladoc/run/SI-3484.scala | 52 +++++++ test/scaladoc/run/SI-4676.check | 1 + test/scaladoc/run/SI-4676.scala | 26 ++++ test/scaladoc/run/SI-5235.scala | 6 +- test/scaladoc/run/implicits-var-exp.scala | 35 +++-- test/scaladoc/scalacheck/HtmlFactoryTest.scala | 73 +++------- 25 files changed, 459 insertions(+), 204 deletions(-) create mode 100644 test/scaladoc/resources/SI-3314.scala delete mode 100644 test/scaladoc/resources/SI_4676.scala delete mode 100644 test/scaladoc/resources/Trac3484.scala create mode 100644 test/scaladoc/run/SI-3314.check create mode 100644 test/scaladoc/run/SI-3314.scala create mode 100644 test/scaladoc/run/SI-3484.check create mode 100644 test/scaladoc/run/SI-3484.scala create mode 100644 test/scaladoc/run/SI-4676.check create mode 100644 test/scaladoc/run/SI-4676.scala (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala index 51c5793d46..18cc65092b 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala @@ -138,7 +138,7 @@ class HtmlFactory(val universe: doc.Universe, index: doc.Index) { if (!(written contains tpl)) { writeForThis(new page.Template(universe, diagramGenerator, tpl)) written += tpl - tpl.templates map writeTemplate + tpl.templates collect { case d: DocTemplateEntity => d } map writeTemplate } } diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala index 4a1a8cf898..af5e90083e 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala @@ -155,12 +155,18 @@ abstract class HtmlPage extends Page { thisPage => def toLinksIn(inPos: Int, starts: List[Int]): NodeSeq = { val (tpl, width) = tpe.refEntity(inPos) (tpl match { - case dtpl:DocTemplateEntity if hasLinks => + case LinkToTpl(dtpl:DocTemplateEntity) if hasLinks => { string.slice(inPos, inPos + width) } - case tpl => + case LinkToTpl(tpl) => { string.slice(inPos, inPos + width) } + case LinkToMember(mbr, inTpl) if hasLinks => + { + string.slice(inPos, inPos + width) + } + case LinkToMember(mbr, inTpl) => + { string.slice(inPos, inPos + width) } }) ++ toLinksOut(inPos + width, starts.tail) } if (hasLinks) diff --git a/src/compiler/scala/tools/nsc/doc/html/Page.scala b/src/compiler/scala/tools/nsc/doc/html/Page.scala index 5e3ab87ccd..08df26e745 100644 --- a/src/compiler/scala/tools/nsc/doc/html/Page.scala +++ b/src/compiler/scala/tools/nsc/doc/html/Page.scala @@ -48,7 +48,7 @@ abstract class Page { * @param generator The generator that is writing this page. */ def writeFor(site: HtmlFactory): Unit - def docEntityKindToString(ety: DocTemplateEntity) = + def docEntityKindToString(ety: TemplateEntity) = if (ety.isTrait) "trait" else if (ety.isCaseClass) "case class" else if (ety.isClass) "class" diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala index 0e894a03bf..ba48bf3f9b 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala @@ -61,7 +61,9 @@ class Index(universe: doc.Universe, index: doc.Index) extends HtmlPage { }
    { val tpls: Map[String, Seq[DocTemplateEntity]] = - (pack.templates filter (t => !t.isPackage && !universe.settings.hardcoded.isExcluded(t.qualifiedName) )) groupBy (_.name) + (pack.templates collect { + case t: DocTemplateEntity if !t.isPackage && !universe.settings.hardcoded.isExcluded(t.qualifiedName) => t + }) groupBy (_.name) val placeholderSeq: NodeSeq =
    diff --git a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala index 2b68ac2937..e1ab479f9d 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala @@ -62,7 +62,9 @@ class IndexScript(universe: doc.Universe, index: doc.Index) extends Page { def allPackagesWithTemplates = { Map(allPackages.map((key) => { - key -> key.templates.filter(t => !t.isPackage && !universe.settings.hardcoded.isExcluded(t.qualifiedName)) + key -> key.templates.collect { + case t: DocTemplateEntity if !t.isPackage && !universe.settings.hardcoded.isExcluded(t.qualifiedName) => t + } }) : _*) } } 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 0d0410c7e2..47834e542c 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -238,44 +238,12 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp } - def boundsToString(hi: Option[TypeEntity], lo: Option[TypeEntity]): String = { - def bound0(bnd: Option[TypeEntity], pre: String): String = bnd match { - case None => "" - case Some(tpe) => pre ++ tpe.toString - } - bound0(hi, "<:") ++ bound0(lo, ">:") - } - - def tparamsToString(tpss: List[TypeParam]): String = { - if (tpss.isEmpty) "" else { - def tparam0(tp: TypeParam): String = - tp.variance + tp.name + boundsToString(tp.hi, tp.lo) - def tparams0(tpss: List[TypeParam]): String = (tpss: @unchecked) match { - case tp :: Nil => tparam0(tp) - case tp :: tps => tparam0(tp) ++ ", " ++ tparams0(tps) - } - "[" + tparams0(tpss) + "]" - } - } - - def defParamsToString(d: MemberEntity with Def): String = { - val paramLists: List[String] = - if (d.valueParams.isEmpty) Nil - else d.valueParams map (ps => ps map (_.resultType.name) mkString ("(",",",")")) - - tparamsToString(d.typeParams) + paramLists.mkString - } - def memberToHtml(mbr: MemberEntity, inTpl: DocTemplateEntity): NodeSeq = { - val defParamsString = mbr match { - case d:MemberEntity with Def => defParamsToString(d) - case _ => "" - } val memberComment = memberToCommentHtml(mbr, inTpl, false)
  1. - + { signature(mbr, false) } { memberComment }
    2. @@ -650,6 +618,7 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp def kindToString(mbr: MemberEntity): String = { mbr match { case tpl: DocTemplateEntity => docEntityKindToString(tpl) + case tpl: NoDocTemplateMemberEntity => docEntityKindToString(tpl) case ctor: Constructor => "new" case tme: MemberEntity => ( if (tme.isDef) "def" @@ -850,18 +819,13 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp val link = relativeLinkTo(mbr) myXml ++= {str.substring(from, to)} case mbr: MemberEntity => - val anchor = "#" + mbr.name + defParamsString(mbr) + ":" + mbr.resultType.name + val anchor = "#" + mbr.signature val link = relativeLinkTo(mbr.inTemplate) myXml ++= {str.substring(from, to)} } index = to } } - // function used in the MemberEntity case above - def defParamsString(mbr: Entity):String = mbr match { - case d:MemberEntity with Def => defParamsToString(d) - case _ => "" - } if (index <= length-1) myXml ++= codeStringToXml(str.substring(index, length )) 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 dc6f941c30..8648fdb0a1 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 @@ -74,7 +74,7 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { def textTypeEntity(text: String) = new TypeEntity { val name = text - def refEntity: SortedMap[Int, (TemplateEntity, Int)] = SortedMap() + def refEntity: SortedMap[Int, (LinkTo, Int)] = SortedMap() } // it seems dot chokes on node names over 8000 chars, so let's limit the size of the string diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index 2901daafd6..4ab77b356b 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -53,6 +53,9 @@ trait Entity { /** The kind of the entity */ def kind: String + + /** Whether or not the template was defined in a package object */ + def inPackageObject: Boolean } object Entity { @@ -91,9 +94,6 @@ trait TemplateEntity extends Entity { /** Whether this template is a case class. */ def isCaseClass: Boolean - /** Whether or not the template was defined in a package object */ - def inPackageObject: Boolean - /** The self-type of this template, if it differs from the template type. */ def selfType : Option[TypeEntity] @@ -183,7 +183,11 @@ trait MemberEntity extends Entity { /** If this member originates from an implicit conversion, we set the implicit information to the correct origin */ def byConversion: Option[ImplicitConversion] + + /** The identity of this member, used for linking */ + def signature: String } + object MemberEntity { // Oh contravariance, contravariance, wherefore art thou contravariance? // Note: the above works for both the commonly misunderstood meaning of the line and the real one. @@ -205,7 +209,10 @@ trait NoDocTemplate extends TemplateEntity { def kind = "" } -/** TODO: Document */ +/** An inherited template that was not documented in its original owner - example: + * in classpath: trait T { class C } -- T (and implicitly C) are not documented + * in the source: trait U extends T -- C appears in U as a NoDocTemplateMemberImpl + * -- that is, U has a member for it but C doesn't get its own page */ trait NoDocTemplateMemberEntity extends TemplateEntity with MemberEntity { def kind = "" } @@ -253,7 +260,7 @@ trait DocTemplateEntity extends TemplateEntity with 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] + def templates: List[TemplateEntity with MemberEntity] /** All methods that are members of this template. */ def methods: List[Def] diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 9fa6619e9f..2efbfbe43c 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -83,6 +83,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def toRoot: List[EntityImpl] = this :: inTpl.toRoot def qualifiedName = name def annotations = sym.annotations.map(makeAnnotation) + def inPackageObject: Boolean = sym.owner.isModuleClass && sym.owner.sourceModule.isPackageObject } trait TemplateImpl extends EntityImpl with TemplateEntity { @@ -96,11 +97,25 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def isRootPackage = false def ownType = makeType(sym.tpe, this) def selfType = if (sym.thisSym eq sym) None else Some(makeType(sym.thisSym.typeOfThis, this)) - def inPackageObject: Boolean = sym.owner.isModuleClass && sym.owner.sourceModule.isPackageObject } abstract class MemberImpl(sym: Symbol, implConv: ImplicitConversionImpl, inTpl: DocTemplateImpl) extends EntityImpl(sym, inTpl) with MemberEntity { - lazy val comment = if (inTpl != null) thisFactory.comment(sym, inTpl) else None + lazy val comment = { + val commentTpl = + /* Variable precendence order for implicitly added members: Take the variable defifinitions from ... + * 1. the target of the implicit conversion + * 2. the definition template (owner) + * 3. the current template + */ + if (implConv != null) findTemplateMaybe(implConv.toType.typeSymbol) match { + case Some(d) if d != makeRootPackage => d //in case of NoSymbol, it will give us the root package + case _ => findTemplateMaybe(sym.owner) match { + case Some(d) if d != makeRootPackage => d //in case of NoSymbol, it will give us the root package + case _ => inTpl + } + } else inTpl + if (commentTpl != null) thisFactory.comment(sym, commentTpl) else None + } override def inTemplate = inTpl override def toRoot: List[MemberImpl] = this :: inTpl.toRoot def inDefinitionTemplates = this match { @@ -189,6 +204,30 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { sym.isAbstractClass || sym.isAbstractType) && !sym.isSynthetic def isTemplate = false def byConversion = if (implConv ne null) Some(implConv) else None + lazy val signature = { + + val defParamsString = this match { + case d: MemberEntity with Def => + val paramLists: List[String] = + if (d.valueParams.isEmpty) Nil + else d.valueParams map (ps => ps map (_.resultType.name) mkString ("(",",",")")) + + val tParams = if (d.typeParams.isEmpty) "" else { + def boundsToString(hi: Option[TypeEntity], lo: Option[TypeEntity]): String = { + def bound0(bnd: Option[TypeEntity], pre: String): String = bnd match { + case None => "" + case Some(tpe) => pre ++ tpe.toString + } + bound0(hi, "<:") ++ bound0(lo, ">:") + } + "[" + d.typeParams.map(tp => tp.variance + tp.name + boundsToString(tp.hi, tp.lo)).mkString(", ") + "]" + } + + tParams + paramLists.mkString + case _ => "" + } + name + defParamsString +":"+ resultType.name + } } /** A template that is not documented at all. The class is instantiated during lookups, to indicate that the class @@ -198,7 +237,6 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { assert(modelFinished) assert(!(noDocTemplatesCache isDefinedAt sym)) noDocTemplatesCache += (sym -> this) - def isDocTemplate = false } @@ -209,7 +247,8 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { */ class NoDocTemplateMemberImpl(sym: Symbol, inTpl: DocTemplateImpl) extends MemberImpl(sym, null, inTpl) with TemplateImpl with HigherKindedImpl with NoDocTemplateMemberEntity { assert(modelFinished) - + // no templates cache for this class, each owner gets its own instance + override def isTemplate = true def isDocTemplate = false lazy val definitionName = optimize(inDefinitionTemplates.head.qualifiedName + "." + name) } @@ -330,7 +369,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { // all the members that are documentented PLUS the members inherited by implicit conversions var members: List[MemberImpl] = ownMembers - def templates = members collect { case c: DocTemplateEntity => c } + def templates = members collect { case c: TemplateEntity with MemberEntity => c } def methods = members collect { case d: Def => d } def values = members collect { case v: Val => v } def abstractTypes = members collect { case t: AbstractType => t } @@ -348,7 +387,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { case _ => } - members :::= memberSymsLazy.map(modelCreation.createLazyTemplateMember(_, inTpl)) + members :::= memberSymsLazy.map(modelCreation.createLazyTemplateMember(_, this)) // compute linearization to register subclasses linearization @@ -411,9 +450,14 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { abstract class NonTemplateMemberImpl(sym: Symbol, implConv: ImplicitConversionImpl, inTpl: DocTemplateImpl) extends MemberImpl(sym, implConv, inTpl) with NonTemplateMemberEntity { override def qualifiedName = optimize(inTemplate.qualifiedName + "#" + name) - lazy val definitionName = - if (implConv == null) optimize(inDefinitionTemplates.head.qualifiedName + "#" + name) - else optimize(implConv.conversionQualifiedName + "#" + name) + lazy val definitionName = { + // this contrived name is here just to satisfy some older tests -- if you decide to remove it, be my guest, and + // also remove property("package object") from test/scaladoc/scalacheck/HtmlFactoryTest.scala so you don't break + // the test suite... + val packageObject = if (inPackageObject) ".package" else "" + if (implConv == null) optimize(inDefinitionTemplates.head.qualifiedName + packageObject + "#" + name) + else optimize(implConv.conversionQualifiedName + packageObject + "#" + name) + } def isUseCase = sym.isSynthetic def isBridge = sym.isBridge } @@ -461,7 +505,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { case ObjectClass => normalizeTemplate(AnyRefClass) case _ if aSym.isPackageObject => - aSym + normalizeTemplate(aSym.owner) case _ if aSym.isModuleClass => normalizeTemplate(aSym.sourceModule) case _ => @@ -501,6 +545,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { } def createDocTemplate(bSym: Symbol, inTpl: DocTemplateImpl): DocTemplateImpl = { + assert(!modelFinished) // only created BEFORE the model is finished if (bSym.isModule || (bSym.isAliasType && bSym.tpe.typeSymbol.isModule)) new DocTemplateImpl(bSym, inTpl) with Object else if (bSym.isTrait || (bSym.isAliasType && bSym.tpe.typeSymbol.isTrait)) @@ -566,6 +611,13 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { * - NoDocTemplateEntity (created in makeTemplate) */ def createLazyTemplateMember(aSym: Symbol, inTpl: DocTemplateImpl): MemberImpl = { + + // Code is duplicate because the anonymous classes are created statically + def createNoDocMemberTemplate(bSym: Symbol, inTpl: DocTemplateImpl): NoDocTemplateMemberImpl = { + assert(modelFinished) // only created AFTER the model is finished + new NoDocTemplateMemberImpl(bSym, inTpl) + } + assert(modelFinished) val bSym = normalizeTemplate(aSym) @@ -579,7 +631,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { mbrs.head case _ => // move the class completely to the new location - new NoDocTemplateMemberImpl(aSym, inTpl) + createNoDocMemberTemplate(bSym, inTpl) } } } @@ -690,7 +742,9 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { docTemplatesCache.get(normalizeTemplate(aSym)) } - def makeTemplate(aSym: Symbol): TemplateImpl = { + def makeTemplate(aSym: Symbol): TemplateImpl = makeTemplate(aSym, None) + + def makeTemplate(aSym: Symbol, inTpl: Option[TemplateImpl]): TemplateImpl = { assert(modelFinished) def makeNoDocTemplate(aSym: Symbol, inTpl: TemplateImpl): NoDocTemplateImpl = { @@ -706,7 +760,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { dtpl case None => val bSym = normalizeTemplate(aSym) - makeNoDocTemplate(bSym, makeTemplate(bSym.owner)) + makeNoDocTemplate(bSym, if (inTpl.isDefined) inTpl.get else makeTemplate(bSym.owner)) } } @@ -797,10 +851,10 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { /** Get the types of the parents of the current class, ignoring the refinements */ def makeParentTypes(aType: Type, tpl: Option[DocTemplateImpl], inTpl: TemplateImpl): List[(TemplateEntity, TypeEntity)] = aType match { case RefinedType(parents, defs) => - val ignoreParents = Set[Symbol](AnyRefClass, ObjectClass) + val ignoreParents = Set[Symbol](AnyClass, AnyRefClass, ObjectClass) val filtParents = // we don't want to expose too many links to AnyRef, that will just be redundant information - if (tpl.isDefined && (!tpl.get.isObject && parents.length < 2)) + if (tpl.isDefined && { val sym = tpl.get.sym; (!sym.isModule && parents.length < 2) || (sym == AnyValClass) || (sym == AnyRefClass) || (sym == AnyClass) }) parents else parents.filterNot((p: Type) => ignoreParents(p.typeSymbol)) @@ -819,7 +873,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def createTypeEntity = new TypeEntity { private val nameBuffer = new StringBuilder - private var refBuffer = new immutable.TreeMap[Int, (TemplateEntity, Int)] + private var refBuffer = new immutable.TreeMap[Int, (LinkTo, Int)] private def appendTypes0(types: List[Type], sep: String): Unit = types match { case Nil => case tp :: Nil => @@ -862,15 +916,56 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { // if (!preSym.printWithoutPrefix) { // nameBuffer append stripPrefixes.foldLeft(pre.prefixString)(_ stripPrefix _) // } + + // SI-3314/SI-4888: Classes, Traits and Types can be inherited from a template to another: + // class Enum { abstract class Value } + // class Day extends Enum { object Mon extends Value /*...*/ } + // ===> in such cases we have two options: + // (0) if there's no inheritance taking place (Enum#Value) we can link to the template directly + // (1) if we generate the doc template for Day, we can link to the correct member + // (2) if we don't generate the doc template, we should at least indicate the correct prefix in the tooltip val bSym = normalizeTemplate(aSym) - if (bSym.isNonClassType && bSym != AnyRefClass) { - nameBuffer append bSym.decodedName - } else { - val tpl = makeTemplate(bSym) - val pos0 = nameBuffer.length - refBuffer += pos0 -> (tpl, tpl.name.length) - nameBuffer append tpl.name - } + val owner = + if ((preSym != NoSymbol) && /* it needs a prefix */ + (preSym != bSym.owner) && /* prefix is different from owner */ + // ((preSym != inTpl.sym) && /* prevent prefixes from being shown inside the defining class */ + // (preSym != inTpl.sym.moduleClass)) && /* or object */ + (aSym == bSym)) /* normalization doesn't play tricks on us */ + preSym + else + bSym.owner + + val bTpl = findTemplateMaybe(bSym) + val link = + if (owner == bSym.owner && bTpl.isDefined) + // (0) the owner's class is linked AND has a template - lovely + LinkToTpl(bTpl.get) + else { + val oTpl = findTemplateMaybe(owner) + val bMbr = oTpl.map(findMember(bSym, _)) + if (oTpl.isDefined && bMbr.isDefined && bMbr.get.isDefined) + // (1) the owner's class + LinkToMember(bMbr.get.get, oTpl.get) //ugh + else + // (2) if we still couldn't find the owner, make a noDocTemplate for everything (in the correct owner!) + LinkToTpl(makeTemplate(bSym, Some(makeTemplate(owner)))) + } + + // TODO: The name might include a prefix, take care of that! + val name = bSym.nameString + val pos0 = nameBuffer.length + refBuffer += pos0 -> ((link, name.length)) + nameBuffer append name + + // if (bSym.isNonClassType && bSym != AnyRefClass) { + // nameBuffer append bSym.decodedName + // } else { + // val tpl = makeTemplate(bSym) + // val pos0 = nameBuffer.length + // refBuffer += pos0 -> ((LinkToTpl(tpl), tpl.name.length)) + // nameBuffer append tpl.name + // } + if (!targs.isEmpty) { nameBuffer append '[' appendTypes0(targs, ", ") @@ -949,12 +1044,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { * (1) sourceModule * (2) you get out of owners with .owner */ - normalizeTemplate(aSym) match { - case bSym if bSym.isPackageObject => - normalizeOwner(bSym.owner) - case bSym => - bSym - } + normalizeTemplate(aSym) def inOriginalOnwer(aSym: Symbol, inTpl: TemplateImpl): Boolean = normalizeOwner(aSym.owner) == normalizeOwner(inTpl.sym) diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala index 8cbf2ac1b6..493ad3d831 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala @@ -408,25 +408,14 @@ trait ModelFactoryImplicitSupport { debug("") memberSyms.flatMap({ aSym => - makeTemplate(aSym.owner) match { - case d: DocTemplateImpl => - // we can't just pick up nodes from the previous template, although that would be very convenient: - // they need the byConversion field to be attached to themselves -- this is design decision I should - // revisit soon - // - // d.ownMembers.collect({ - // // it's either a member or has a couple of usecases it's hidden behind - // case m: MemberImpl if m.sym == aSym => - // m // the member itself - // case m: MemberImpl if m.useCaseOf.isDefined && m.useCaseOf.get.asInstanceOf[MemberImpl].sym == aSym => - // m.useCaseOf.get.asInstanceOf[MemberImpl] // the usecase - // }) - makeMember(aSym, this, d) - case _ => - // should only happen if the code for this template is not part of the scaladoc run => - // members won't have any comments - makeMember(aSym, this, inTpl) - } + // we can't just pick up nodes from the original template, although that would be very convenient: + // they need the byConversion field to be attached to themselves and the types to be transformed by + // asSeenFrom + + // at the same time, the member itself is in the inTpl, not in the new template -- but should pick up + // variables from the old template. Ugly huh? We'll always create the member inTpl, but it will change + // the template when expanding variables in the comment :) + makeMember(aSym, this, inTpl) }) } diff --git a/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala b/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala index 67e955f613..a16e99bf06 100644 --- a/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala @@ -9,6 +9,9 @@ package model import scala.collection._ +abstract sealed class LinkTo +case class LinkToTpl(tpl: TemplateEntity) extends LinkTo +case class LinkToMember(mbr: MemberEntity, inTpl: DocTemplateEntity) extends LinkTo /** 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 @@ -21,7 +24,7 @@ abstract class TypeEntity { /** 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)] + def refEntity: SortedMap[Int, (LinkTo, Int)] /** The human-readable representation of this type. */ override def toString = name 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 1a8ad193aa..4b05da98cd 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala @@ -32,7 +32,7 @@ trait DiagramFactory extends DiagramDirectiveParser { def normalNode(sym: Symbol) = NormalNode(makeTemplate(sym).ownType, Some(makeTemplate(sym))) def aggregationNode(text: String) = - NormalNode(new TypeEntity { val name = text; val refEntity = SortedMap[Int, (TemplateEntity, Int)]() }, None) + NormalNode(new TypeEntity { val name = text; val refEntity = SortedMap[Int, (LinkTo, Int)]() }, None) /** Create the inheritance diagram for this template */ def makeInheritanceDiagram(tpl: DocTemplateImpl): Option[Diagram] = { diff --git a/src/partest/scala/tools/partest/ScaladocModelTest.scala b/src/partest/scala/tools/partest/ScaladocModelTest.scala index be70a91e14..c89dd2cb8f 100644 --- a/src/partest/scala/tools/partest/ScaladocModelTest.scala +++ b/src/partest/scala/tools/partest/ScaladocModelTest.scala @@ -103,13 +103,22 @@ abstract class ScaladocModelTest extends DirectTest { class TemplateAccess(tpl: DocTemplateEntity) { def _class(name: String): DocTemplateEntity = getTheFirst(_classes(name), tpl.qualifiedName + ".class(" + name + ")") - def _classes(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case c: Class => c}) + def _classes(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case c: DocTemplateEntity with Class => c}) + + def _classMbr(name: String): NoDocTemplateMemberEntity = getTheFirst(_classesMbr(name), tpl.qualifiedName + ".classMember(" + name + ")") + def _classesMbr(name: String): List[NoDocTemplateMemberEntity] = tpl.templates.filter(_.name == name).collect({ case c: NoDocTemplateMemberEntity if c.isClass => c}) def _trait(name: String): DocTemplateEntity = getTheFirst(_traits(name), tpl.qualifiedName + ".trait(" + name + ")") - def _traits(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case t: Trait => t}) + def _traits(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case t: DocTemplateEntity with Trait => t}) + + def _traitMbr(name: String): NoDocTemplateMemberEntity = getTheFirst(_traitsMbr(name), tpl.qualifiedName + ".traitMember(" + name + ")") + def _traitsMbr(name: String): List[NoDocTemplateMemberEntity] = tpl.templates.filter(_.name == name).collect({ case t: NoDocTemplateMemberEntity if t.isTrait => t}) def _object(name: String): DocTemplateEntity = getTheFirst(_objects(name), tpl.qualifiedName + ".object(" + name + ")") - def _objects(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case o: Object => o}) + def _objects(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case o: DocTemplateEntity with Object => o}) + + def _objectMbr(name: String): NoDocTemplateMemberEntity = getTheFirst(_objectsMbr(name), tpl.qualifiedName + ".objectMember(" + name + ")") + def _objectsMbr(name: String): List[NoDocTemplateMemberEntity] = tpl.templates.filter(_.name == name).collect({ case o: NoDocTemplateMemberEntity if o.isObject => o}) def _method(name: String): Def = getTheFirst(_methods(name), tpl.qualifiedName + ".method(" + name + ")") def _methods(name: String): List[Def] = tpl.methods.filter(_.name == name) @@ -119,6 +128,12 @@ abstract class ScaladocModelTest extends DirectTest { def _conversion(name: String): ImplicitConversion = getTheFirst(_conversions(name), tpl.qualifiedName + ".conversion(" + name + ")") def _conversions(name: String): List[ImplicitConversion] = tpl.conversions.filter(_.conversionQualifiedName == name) + + def _absType(name: String): MemberEntity = getTheFirst(_methods(name), tpl.qualifiedName + ".abstractType(" + name + ")") + def _absTypes(name: String): List[MemberEntity] = tpl.members.filter(mbr => mbr.name == name && mbr.isAbstractType) + + def _aliasType(name: String): MemberEntity = getTheFirst(_methods(name), tpl.qualifiedName + ".aliasType(" + name + ")") + def _aliasTypes(name: String): List[MemberEntity] = tpl.members.filter(mbr => mbr.name == name && mbr.isAliasType) } class PackageAccess(pack: Package) extends TemplateAccess(pack) { @@ -141,7 +156,10 @@ abstract class ScaladocModelTest extends DirectTest { case 1 => list.head case 0 => sys.error("Error getting " + expl + ": No such element.") case _ => sys.error("Error getting " + expl + ": " + list.length + " elements with this name. " + - "All elements in list: [" + list.mkString(", ") + "]") + "All elements in list: [" + list.map({ + case ent: Entity => ent.kind + " " + ent.qualifiedName + case other => other.toString + }).mkString(", ") + "]") } def extractCommentText(c: Comment) = { diff --git a/test/scaladoc/resources/SI-3314.scala b/test/scaladoc/resources/SI-3314.scala new file mode 100644 index 0000000000..e5773a4970 --- /dev/null +++ b/test/scaladoc/resources/SI-3314.scala @@ -0,0 +1,70 @@ +package scala.test.scaladoc { + + package test1 { + class Enum { + abstract class Value + class Val extends Value + def Value(): Value = new Val + } + + object Constants extends Enum { + def a = Value + } + } + + package test2 { + trait WeekDayTrait extends Enumeration { + type WeekDay = Value + val Mon, Tue, Wed, Thu, Fri, Sat, Sun = Value + } + + class WeekDayClass extends Enumeration { + type WeekDay = Value + val Mon, Tue, Wed, Thu, Fri, Sat, Sun = Value + } + + object WeekDayObject extends Enumeration { + type WeekDay = Value + val Mon, Tue, Wed, Thu, Fri, Sat, Sun = Value + } + + object UserObject { + def isWorkingDay1(d: scala.test.scaladoc.test2.WeekDayClass#Value) = false + def isWorkingDay2(d: scala.test.scaladoc.test2.WeekDayClass#WeekDay) = false + def isWorkingDay3(d: scala.test.scaladoc.test2.WeekDayTrait#Value) = false + def isWorkingDay4(d: scala.test.scaladoc.test2.WeekDayTrait#WeekDay) = false + def isWorkingDay5(d: scala.test.scaladoc.test2.WeekDayObject.Value) = false + def isWorkingDay6(d: scala.test.scaladoc.test2.WeekDayObject.WeekDay) = false + import WeekDayObject._ + def isWorkingDay7(d: Value) = ! (d == Sat || d == Sun) + def isWorkingDay8(d: WeekDay) = ! (d == Sat || d == Sun) + def isWorkingDay9(d: WeekDayObject.Value) = ! (d == Sat || d == Sun) + } + + class UserClass { + def isWorkingDay1(d: scala.test.scaladoc.test2.WeekDayClass#Value) = false + def isWorkingDay2(d: scala.test.scaladoc.test2.WeekDayClass#WeekDay) = false + def isWorkingDay3(d: scala.test.scaladoc.test2.WeekDayTrait#Value) = false + def isWorkingDay4(d: scala.test.scaladoc.test2.WeekDayTrait#WeekDay) = false + def isWorkingDay5(d: scala.test.scaladoc.test2.WeekDayObject.Value) = false + def isWorkingDay6(d: scala.test.scaladoc.test2.WeekDayObject.WeekDay) = false + import WeekDayObject._ + def isWorkingDay7(d: Value) = ! (d == Sat || d == Sun) + def isWorkingDay8(d: WeekDay) = ! (d == Sat || d == Sun) + def isWorkingDay9(d: WeekDayObject.Value) = ! (d == Sat || d == Sun) + } + + trait UserTrait { + def isWorkingDay1(d: scala.test.scaladoc.test2.WeekDayClass#Value) = false + def isWorkingDay2(d: scala.test.scaladoc.test2.WeekDayClass#WeekDay) = false + def isWorkingDay3(d: scala.test.scaladoc.test2.WeekDayTrait#Value) = false + def isWorkingDay4(d: scala.test.scaladoc.test2.WeekDayTrait#WeekDay) = false + def isWorkingDay5(d: scala.test.scaladoc.test2.WeekDayObject.Value) = false + def isWorkingDay6(d: scala.test.scaladoc.test2.WeekDayObject.WeekDay) = false + import WeekDayObject._ + def isWorkingDay7(d: Value) = ! (d == Sat || d == Sun) + def isWorkingDay8(d: WeekDay) = ! (d == Sat || d == Sun) + def isWorkingDay9(d: WeekDayObject.Value) = ! (d == Sat || d == Sun) + } + } +} diff --git a/test/scaladoc/resources/SI_4676.scala b/test/scaladoc/resources/SI_4676.scala deleted file mode 100644 index 00c0fc7ea9..0000000000 --- a/test/scaladoc/resources/SI_4676.scala +++ /dev/null @@ -1,4 +0,0 @@ -class SI_4676 { - type SS = (String,String) - def x(ss: SS): Int = 3 -} diff --git a/test/scaladoc/resources/Trac3484.scala b/test/scaladoc/resources/Trac3484.scala deleted file mode 100644 index 9656ec268d..0000000000 --- a/test/scaladoc/resources/Trac3484.scala +++ /dev/null @@ -1,27 +0,0 @@ -class cbf[A, B, C] - -/** - * @define Coll Traversable - * @define bfreturn $Coll - */ -class Collection[A] { - /** What map does... - * - * $bfreturn - * @usecase def map[B](f: A => B): $bfreturn[B] - * - */ - def map[B, That](f: A => B)(implicit fact: cbf[Collection[A], B, That]) = - null -} - -/** - * @define b John - * @define a Mister $b - */ -class SR704 { - /** - * Hello $a. - */ - def foo = 123 -} diff --git a/test/scaladoc/run/SI-3314.check b/test/scaladoc/run/SI-3314.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-3314.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-3314.scala b/test/scaladoc/run/SI-3314.scala new file mode 100644 index 0000000000..665223098a --- /dev/null +++ b/test/scaladoc/run/SI-3314.scala @@ -0,0 +1,74 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def resourceFile = "SI-3314.scala" + + // no need for special settings + def scaladocSettings = "" + + 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 test1 = base._package("test1") + val test1Value = test1._class("Enum")._method("Value").resultType + assert(test1Value.name == "Value", test1Value.name + " == Value") + assert(test1Value.refEntity.size == 1, test1Value.refEntity.size + " == 1") + + val test1Constants = test1._object("Constants")._method("a").resultType + assert(test1Constants.name == "Value", test1Constants.name + " == Value") + assert(test1Constants.refEntity.size == 1, test1Constants.refEntity.size + " == 1") + assert(test1Constants.refEntity(0)._1 == LinkToMember(test1._object("Constants")._class("Value"), test1._object("Constants")), + test1Constants.refEntity(0)._1 + " == LinkToMember(test1.Enum.Value)") + + val test2 = base._package("test2") + def testDefinition(doc: DocTemplateEntity) = { + for (day <- List("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")) { + assert(doc._value(day).resultType.name == "Value", + doc._value(day).resultType.name + " == Value") + assert(doc._value(day).resultType.refEntity.size == 1, + doc._value(day).resultType.refEntity.size + " == 1") + assert(doc._value(day).resultType.refEntity(0)._1 == LinkToMember(doc._classMbr("Value"), doc), + doc._value(day).resultType.refEntity(0)._1 + " == LinkToMember(" + doc.qualifiedName + ".Value)") + } + } + testDefinition(test2._trait("WeekDayTrait")) + testDefinition(test2._class("WeekDayClass")) + testDefinition(test2._object("WeekDayObject")) + + def testUsage(doc: DocTemplateEntity) = { + val ValueInClass = test2._class("WeekDayClass")._classMbr("Value") + val ValueInTrait = test2._trait("WeekDayTrait")._classMbr("Value") + val ValueInObject = test2._object("WeekDayObject")._classMbr("Value") + val WeekDayInObject = test2._object("WeekDayObject")._member("WeekDay") + + val expected = List( + ("isWorkingDay1", "Value", ValueInClass), + ("isWorkingDay2", "Value", ValueInClass), + ("isWorkingDay3", "Value", ValueInTrait), + ("isWorkingDay4", "Value", ValueInTrait), + ("isWorkingDay5", "Value", ValueInObject), + ("isWorkingDay6", "WeekDay", WeekDayInObject), + ("isWorkingDay7", "Value", ValueInObject), + ("isWorkingDay8", "WeekDay", WeekDayInObject), + ("isWorkingDay9", "Value", ValueInObject)) + + for ((method, name, ref) <- expected) { + assert(doc._method(method).valueParams(0)(0).resultType.name == name, + doc._method(method).valueParams(0)(0).resultType.name + " == " + name + " (in " + doc + "." + method + ")") + assert(doc._method(method).valueParams(0)(0).resultType.refEntity.size == 1, + doc._method(method).valueParams(0)(0).resultType.refEntity.size + " == " + 1 + " (in " + doc + "." + method + ")") + assert(doc._method(method).valueParams(0)(0).resultType.refEntity(0)._1 == LinkToMember(ref, ref.inTemplate), + doc._method(method).valueParams(0)(0).resultType.refEntity(0)._1 + " == LinkToMember(" + ref.qualifiedName + ") (in " + doc + "." + method + ")") + } + } + testUsage(test2._object("UserObject")) + testUsage(test2._class("UserClass")) + testUsage(test2._trait("UserTrait")) + } +} \ No newline at end of file diff --git a/test/scaladoc/run/SI-3484.check b/test/scaladoc/run/SI-3484.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-3484.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-3484.scala b/test/scaladoc/run/SI-3484.scala new file mode 100644 index 0000000000..297aebee8f --- /dev/null +++ b/test/scaladoc/run/SI-3484.scala @@ -0,0 +1,52 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.nsc.doc.model.diagram._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def code = """ + class cbf[A, B, C] + + /** + * @define Coll Collection + * @define bfreturn $Coll + */ + class Collection[A] { + /** What map does... + * + * $bfreturn + * @usecase def map[B](f: A => B): $bfreturn[B] + * + */ + def map[B, That](f: A => B)(implicit fact: cbf[Collection[A], B, That]) = + null + } + + /** + * @define b John + * @define a Mister $b + */ + class SR704 { + /** + * Hello $a. + */ + def foo = 123 + } + """ + + // diagrams must be started. In case there's an error with dot, it should not report anything + def scaladocSettings = "" + + 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._ + + // check correct expansion of the use case signature + val map = rootPackage._class("Collection")._method("map") + assert(map.resultType.name == "Collection[B]", map.resultType.name + " == Traversable[B]") + + val foo = rootPackage._class("SR704")._method("foo") + assert(extractCommentText(foo.comment.get).contains("Hello Mister John."), + extractCommentText(foo.comment.get) + ".contains(Hello Mister John.)") + } +} \ No newline at end of file diff --git a/test/scaladoc/run/SI-4676.check b/test/scaladoc/run/SI-4676.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-4676.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-4676.scala b/test/scaladoc/run/SI-4676.scala new file mode 100644 index 0000000000..b83a59a472 --- /dev/null +++ b/test/scaladoc/run/SI-4676.scala @@ -0,0 +1,26 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.nsc.doc.model.diagram._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def code = """ + class SI_4676 { + type SS = (String,String) + def x(ss: SS): Int = 3 + } + class cbf[A, B, C] + """ + + // diagrams must be started. In case there's an error with dot, it should not report anything + def scaladocSettings = "" + + 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._ + + // check correct expansion of the use case signature + val x = rootPackage._class("SI_4676")._method("x") + assert(x.valueParams(0)(0).resultType.name == "(String, String)", "parameter ss of method x has type (String, String") + } +} \ No newline at end of file diff --git a/test/scaladoc/run/SI-5235.scala b/test/scaladoc/run/SI-5235.scala index cae70fd0a5..f0c6e1cf17 100644 --- a/test/scaladoc/run/SI-5235.scala +++ b/test/scaladoc/run/SI-5235.scala @@ -77,11 +77,11 @@ object Test extends ScaladocModelTest { assert(gcReverseType.name == "GenericColl", gcReverseType.name + " == GenericColl") assert(scReverseType.name == "BullSh", scReverseType.name + " == BullSh") assert(mcReverseType.name == "MyCollection",mcReverseType.name + " == MyCollection") - assert(gcReverseType.refEntity(0)._1 == GenericColl, + assert(gcReverseType.refEntity(0)._1 == LinkToTpl(GenericColl), gcReverse.qualifiedName + "'s return type has a link to " + GenericColl.qualifiedName) - assert(scReverseType.refEntity.isEmpty, + assert(!scReverseType.refEntity(0)._1.asInstanceOf[LinkToTpl].tpl.isDocTemplate, scReverse.qualifiedName + "'s return type does not have links") - assert(mcReverseType.refEntity(0)._1 == MyCollection, + assert(mcReverseType.refEntity(0)._1 == LinkToTpl(MyCollection), mcReverse.qualifiedName + "'s return type has a link to " + MyCollection.qualifiedName) } } \ No newline at end of file diff --git a/test/scaladoc/run/implicits-var-exp.scala b/test/scaladoc/run/implicits-var-exp.scala index 16569fe3c2..94d2990d29 100644 --- a/test/scaladoc/run/implicits-var-exp.scala +++ b/test/scaladoc/run/implicits-var-exp.scala @@ -6,25 +6,36 @@ object Test extends ScaladocModelTest { override def code = """ package scala.test.scaladoc.variable.expansion { - /** - * Blah blah blah - */ + /** @define coll WROOOONG-A */ class A object A { import language.implicitConversions - implicit def aToB(a: A) = new B + implicit def aToC(a: A) = new C + implicit def aToE(a: A) = new E with F } - /** - * @define coll collection - */ + /** @define coll WROOOONG-B */ class B { - /** - * foo returns a $coll - */ + /** foo returns a $coll */ def foo: Nothing = ??? } + + /** @define coll collection */ + class C extends B + + /** @define coll WROOOONG-D */ + trait D { + /** bar returns a $coll */ + def bar: Nothing = ??? + } + + /** @define coll result */ + //trait E { self: D => override def bar: Nothing = ??? } + trait E extends D { override def bar: Nothing = ??? } + + /** @define coll WROOOONG-F */ + trait F } """ @@ -37,7 +48,9 @@ object Test extends ScaladocModelTest { val base = rootPackage._package("scala")._package("test")._package("scaladoc")._package("variable")._package("expansion") val foo = base._class("A")._method("foo") - assert(foo.comment.get.body.toString.contains("foo returns a collection"), "\"" + foo.comment.get.body.toString + "\".contains(\"foo returns a collection\")") + + val bar = base._class("A")._method("bar") + assert(bar.comment.get.body.toString.contains("bar returns a result"), "\"" + bar.comment.get.body.toString + "\".contains(\"bar returns a result\")") } } \ No newline at end of file diff --git a/test/scaladoc/scalacheck/HtmlFactoryTest.scala b/test/scaladoc/scalacheck/HtmlFactoryTest.scala index 5b6f75426e..13eacf79a5 100644 --- a/test/scaladoc/scalacheck/HtmlFactoryTest.scala +++ b/test/scaladoc/scalacheck/HtmlFactoryTest.scala @@ -235,30 +235,6 @@ object Test extends Properties("HtmlFactory") { } } - property("Trac #3484") = { - val files = createTemplates("Trac3484.scala") - - files("Collection.html") match { - case node: scala.xml.Node => { - val s = node.toString - s.contains(""": Traversable[B]""") - } - case _ => false - } - } - - property("Trac #3484 - SR704") = { - val files = createTemplates("Trac3484.scala") - - files("SR704.html") match { - case node: scala.xml.Node => { - val s = node.toString - s.contains("Hello Mister John.") - } - case _ => false - } - } - property("Trac #4325 - files") = { val files = createTemplates("Trac4325.scala") @@ -303,7 +279,7 @@ object Test extends Properties("HtmlFactory") { case _ => false } } - // + // // property("Trac #484 - refinements and existentials") = { // val files = createTemplates("Trac484.scala") // val lines = """ @@ -315,7 +291,7 @@ object Test extends Properties("HtmlFactory") { // |def j(x: Int): Bar // |def k(): AnyRef { type Dingus <: T forSome { type T <: String } } // """.stripMargin.trim.lines map (_.trim) - // + // // files("RefinementAndExistentials.html") match { // case node: scala.xml.Node => { // val s = node.text.replaceAll("\\s+", " ") @@ -397,26 +373,17 @@ object Test extends Properties("HtmlFactory") { } } - property("Should decode symbolic type alias name.") = { + property("SI-4714: Should decode symbolic type alias name.") = { createTemplate("SI_4715.scala") match { case node: scala.xml.Node => { val html = node.toString - html.contains(">: :+:[<") - } - case _ => false - } - } - - property("Shouldn't drop type arguments to aliased tuple.") = { - createTemplate("SI_4676.scala") match { - case node: scala.xml.Node => { - node.toString.contains(">ss: (String, String)<") + html.contains(">:+:<") } case _ => false } } - property("Default arguments of synthesized constructor") = { + property("SI-4287: Default arguments of synthesized constructor") = { val files = createTemplates("SI_4287.scala") files("ClassWithSugar.html") match { @@ -427,7 +394,7 @@ object Test extends Properties("HtmlFactory") { } } - property("Default arguments of synthesized constructor") = { + property("SI-4507: Default arguments of synthesized constructor") = { createTemplate("SI_4507.scala") match { case node: scala.xml.Node => ! node.toString.contains("
  2. returns silently when evaluating true and true
    3. ") @@ -435,40 +402,40 @@ object Test extends Properties("HtmlFactory") { } } - property("Use cases and links should not crash scaladoc") = { + property("SI-4898: Use cases and links should not crash scaladoc") = { createTemplate("SI_4898.scala") true } - property("Use cases should override their original members") = + property("SI-5054: Use cases should override their original members") = checkText("SI_5054_q1.scala")( (None,"""def test(): Int""", true) //Disabled because the full signature is now displayed //(None,"""def test(implicit lost: Int): Int""", false) ) - property("Use cases should keep their flags - final should not be lost") = + property("SI-5054: Use cases should keep their flags - final should not be lost") = checkText("SI_5054_q2.scala")((None, """final def test(): Int""", true)) - property("Use cases should keep their flags - implicit should not be lost") = + property("SI-5054: Use cases should keep their flags - implicit should not be lost") = checkText("SI_5054_q3.scala")((None, """implicit def test(): Int""", true)) - property("Use cases should keep their flags - real abstract should not be lost") = + property("SI-5054: Use cases should keep their flags - real abstract should not be lost") = checkText("SI_5054_q4.scala")((None, """abstract def test(): Int""", true)) - property("Use cases should keep their flags - traits should not be affected") = + property("SI-5054: Use cases should keep their flags - traits should not be affected") = checkText("SI_5054_q5.scala")((None, """def test(): Int""", true)) - property("Use cases should keep their flags - traits should not be affected") = + property("SI-5054: Use cases should keep their flags - traits should not be affected") = checkText("SI_5054_q6.scala")((None, """abstract def test(): Int""", true)) - property("Use case individual signature test") = + property("SI-5054: Use case individual signature test") = checkText("SI_5054_q7.scala")( (None, """abstract def test2(explicit: Int): Int [use case] This takes the explicit value passed.""", true), (None, """abstract def test1(): Int [use case] This takes the implicit value in scope.""", true) ) - property("Display correct \"Definition classes\"") = + property("SI-5287: Display correct \"Definition classes\"") = checkText("SI_5287.scala")( (None, """def method(): Int @@ -477,7 +444,7 @@ object Test extends Properties("HtmlFactory") { Definition Classes SI_5287 SI_5287_B SI_5287_A""", true) ) // the explanation appears twice, as small comment and full comment - property("Correct comment inheritance for overriding") = + property("Comment inheritance: Correct comment inheritance for overriding") = checkText("implicit-inheritance-override.scala")( (Some("Base"), """def function[T](arg1: T, arg2: String): Double @@ -521,7 +488,7 @@ object Test extends Properties("HtmlFactory") { ) for (useCaseFile <- List("UseCaseInheritance", "UseCaseOverrideInheritance")) { - property("Correct comment inheritance for usecases") = + property("Comment inheritance: Correct comment inheritance for usecases") = checkText("implicit-inheritance-usecase.scala")( (Some(useCaseFile), """def missing_arg[T](arg1: T): Double @@ -588,7 +555,7 @@ object Test extends Properties("HtmlFactory") { ) } - property("Correct explicit inheritance for override") = + property("Comment inheritance: Correct explicit inheritance for override") = checkText("explicit-inheritance-override.scala")( (Some("InheritDocDerived"), """def function[T](arg1: T, arg2: String): Double @@ -614,7 +581,7 @@ object Test extends Properties("HtmlFactory") { See also StartSee The Manual EndSee """, true)) - property("Correct explicit inheritance for usecase") = + property("Comment inheritance: Correct explicit inheritance for usecase") = checkText("explicit-inheritance-usecase.scala")( (Some("UseCaseInheritDoc"), """def function[T](arg1: T, arg2: String): Double @@ -639,7 +606,7 @@ object Test extends Properties("HtmlFactory") { See also StartSee The Manual EndSee """, true)) - property("Correct explicit inheritance in corner cases") = + property("Comment inheritance: Correct explicit inheritance in corner cases") = checkText("inheritdoc-corner-cases.scala")( (Some("D"), """def hello1: Int -- cgit v1.2.3 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 (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 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 From 242c2fc94766f4dd8b7f1f88ad055f0f62d2e109 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Mon, 2 Jul 2012 17:46:42 +0200 Subject: SI-5558 Package object members indexing This bug was fixed by the model upgrade in c11427c1. Test case confirmation. --- src/compiler/scala/tools/nsc/doc/html/page/Index.scala | 2 +- test/scaladoc/resources/SI-5558.scala | 6 ++++++ test/scaladoc/scalacheck/IndexTest.scala | 13 ++++++++++--- 3 files changed, 17 insertions(+), 4 deletions(-) create mode 100644 test/scaladoc/resources/SI-5558.scala (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala index ba48bf3f9b..81fbed884d 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala @@ -14,7 +14,7 @@ import scala.collection._ import scala.xml._ import scala.util.parsing.json.{JSONObject, JSONArray} -class Index(universe: doc.Universe, index: doc.Index) extends HtmlPage { +class Index(universe: doc.Universe, val index: doc.Index) extends HtmlPage { def path = List("index.html") diff --git a/test/scaladoc/resources/SI-5558.scala b/test/scaladoc/resources/SI-5558.scala new file mode 100644 index 0000000000..6523438b86 --- /dev/null +++ b/test/scaladoc/resources/SI-5558.scala @@ -0,0 +1,6 @@ +package test { + class T + object `package` { + def foo = ??? + } +} diff --git a/test/scaladoc/scalacheck/IndexTest.scala b/test/scaladoc/scalacheck/IndexTest.scala index 29e337da2b..bf385898fc 100644 --- a/test/scaladoc/scalacheck/IndexTest.scala +++ b/test/scaladoc/scalacheck/IndexTest.scala @@ -16,7 +16,7 @@ object Test extends Properties("Index") { val morepaths = Thread.currentThread.getContextClassLoader.getParent.asInstanceOf[URLClassLoader].getURLs.map(u => URLDecoder.decode(u.getPath)) (paths ++ morepaths).mkString(java.io.File.pathSeparator) } - + val docFactory = { val settings = new doc.Settings({Console.err.println(_)}) @@ -27,9 +27,9 @@ object Test extends Properties("Index") { new doc.DocFactory(reporter, settings) } - + val indexModelFactory = doc.model.IndexModelFactory - + def createIndex(path: String): Option[Index] = { val maybeUniverse = { @@ -79,4 +79,11 @@ object Test extends Properties("Index") { case None => false } } + property("package objects in index") = { + createIndex("test/scaladoc/resources/SI-5558.scala") match { + case Some(index) => + index.index.firstLetterIndex('f') isDefinedAt "foo" + case None => false + } + } } -- cgit v1.2.3 From 8779ade6f57ef15a04babf9715bc7ca4cbbdc425 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Mon, 2 Jul 2012 19:43:38 +0200 Subject: SI-4324 Scaladoc case class argument currying case class C(i: Int)(b: Boolean) would appear uncurried in scaladoc: case class C(i: Int, b: Boolean) --- .../scala/tools/nsc/doc/model/ModelFactory.scala | 5 ++++- test/scaladoc/run/SI-4324.check | 1 + test/scaladoc/run/SI-4324.scala | 24 ++++++++++++++++++++++ 3 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 test/scaladoc/run/SI-4324.check create mode 100644 test/scaladoc/run/SI-4324.scala (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 61b4267f3c..25b4a174ec 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -554,7 +554,10 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { new DocTemplateImpl(bSym, inTpl) with Class { def valueParams = // we don't want params on a class (non case class) signature - if (isCaseClass) List(sym.constrParamAccessors map (makeValueParam(_, this))) + if (isCaseClass) primaryConstructor match { + case Some(const) => const.sym.paramss map (_ map (makeValueParam(_, this))) + case None => List() + } else List.empty val constructors = members collect { case d: Constructor => d } diff --git a/test/scaladoc/run/SI-4324.check b/test/scaladoc/run/SI-4324.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-4324.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-4324.scala b/test/scaladoc/run/SI-4324.scala new file mode 100644 index 0000000000..686a133dc0 --- /dev/null +++ b/test/scaladoc/run/SI-4324.scala @@ -0,0 +1,24 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def code = """ + case class Test4324(arg11: String, arg12: Int)(arg21: String, arg22: Int)(arg31: Int, arg32: String) + """ + + // no need for special settings + def scaladocSettings = "" + + 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 + rootPackage._class("Test4324").asInstanceOf[Class].valueParams match { + case List(List(arg11, arg12), List(arg21, arg22), List(arg31, arg32)) => //yeeey, do nothing + case other => + assert(false, "Incorrect valueParams generated: " + other + " instead of (arg11, arg12)(arg21, arg22)(arg31, arg32)") + } + } +} \ No newline at end of file -- cgit v1.2.3 From 891769fae541513d68ce7a8e84b7213472c333c9 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Mon, 2 Jul 2012 20:42:38 +0200 Subject: Scaladoc: workaround for untypical Map usecases SI-3448 partial fix: This enables a workaround for the fact that Map takes two type params while $Coll takes only one. But it doesn't fix the problem though, as there's one more piece missing from the puzzle - we need to adjust the `Coll`s in {immutable, mutable, concurrent}.Map to something that makes sense for the usecase. And that's not possible. But I'm committing this nevertheless, maybe other projects can benefit from it. And for SI-3448, the solution lies in automatic usecase generation, whenever that will be ready. --- src/compiler/scala/tools/nsc/ast/DocComments.scala | 19 ++++++----- test/scaladoc/run/SI-3448.check | 1 + test/scaladoc/run/SI-3448.scala | 38 ++++++++++++++++++++++ 3 files changed, 50 insertions(+), 8 deletions(-) create mode 100644 test/scaladoc/run/SI-3448.check create mode 100644 test/scaladoc/run/SI-3448.scala (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/ast/DocComments.scala b/src/compiler/scala/tools/nsc/ast/DocComments.scala index b2d6800ebb..19af01bda8 100755 --- a/src/compiler/scala/tools/nsc/ast/DocComments.scala +++ b/src/compiler/scala/tools/nsc/ast/DocComments.scala @@ -513,23 +513,25 @@ trait DocComments { self: Global => tstr } - val aliasExpansions: List[Type] = + // the Boolean tells us whether we can normalize: if we found an actual type, then yes, we can normalize, else no, + // use the synthetic alias created for the variable + val aliasExpansions: List[(Type, Boolean)] = for (alias <- aliases) yield lookupVariable(alias.name.toString.substring(1), site) match { case Some(repl) => val repl2 = cleanupVariable(repl) val tpe = getType(repl2, alias.name.toString) - if (tpe != NoType) tpe + if (tpe != NoType) (tpe, true) else { val alias1 = alias.cloneSymbol(rootMirror.RootClass, alias.rawflags, newTypeName(repl2)) - typeRef(NoPrefix, alias1, Nil) + (typeRef(NoPrefix, alias1, Nil), false) } case None => - typeRef(NoPrefix, alias, Nil) + (typeRef(NoPrefix, alias, Nil), false) } - def subst(sym: Symbol, from: List[Symbol], to: List[Type]): Type = - if (from.isEmpty) sym.tpe + def subst(sym: Symbol, from: List[Symbol], to: List[(Type, Boolean)]): (Type, Boolean) = + if (from.isEmpty) (sym.tpe, false) else if (from.head == sym) to.head else subst(sym, from.tail, to.tail) @@ -537,8 +539,9 @@ trait DocComments { self: Global => def apply(tp: Type) = mapOver(tp) match { case tp1 @ TypeRef(pre, sym, args) if (sym.name.length > 1 && sym.name.startChar == '$') => subst(sym, aliases, aliasExpansions) match { - case TypeRef(pre1, sym1, _) => - typeRef(pre1, sym1, args) + case (TypeRef(pre1, sym1, _), canNormalize) => + val tpe = typeRef(pre1, sym1, args) + if (canNormalize) tpe.normalize else tpe case _ => tp1 } diff --git a/test/scaladoc/run/SI-3448.check b/test/scaladoc/run/SI-3448.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-3448.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-3448.scala b/test/scaladoc/run/SI-3448.scala new file mode 100644 index 0000000000..a2d3f59596 --- /dev/null +++ b/test/scaladoc/run/SI-3448.scala @@ -0,0 +1,38 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + // Working around the fact that usecases have the form Coll[T] and not Coll[T, U], as required by Map + override def code = """ + /** + * @define Coll C[T] + */ + class C[T] { + /** + * @usecase def foo[T]: $Coll[T] + */ + def foo[T: Numeric]: C[T] + } + + + /** + * @define Coll D1[T] + */ + class D[U, T] extends C[T] { + protected type D1[Z] = D[U, Z] + } + """ + + // no need for special settings + def scaladocSettings = "" + + 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 + assert(rootPackage._class("D")._method("foo").resultType.name == "D[U, T]", + rootPackage._class("D")._method("foo").resultType.name + " == D[U, T]") + } +} \ No newline at end of file -- cgit v1.2.3 From a119ad1ae58723bd2e757ed331a536ff4ae49bdf Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Thu, 12 Jul 2012 14:24:54 +0200 Subject: SI-4360 Adds prefixes to scaladoc This was a long-standing issue in scaladoc: It was unable to disambiguate between entries with the same name. One example is: immutable.Seq: trait Seq[+A] extends Iterable[A] with Seq[A] ... What's that? Seq extends Seq? No, immutable.Seq extends collection.Seq, but scaladoc was unable to show that. Now it does, depending on the template you're in. Prefixes are relative and can go back: -scala.collection.Seq has subclasses *immutable.Seq* and *mutable.Seq* -scala.immutable.Seq extends *collection.Seq* Unfortunately the price we pay for this is high, a 20% slowdown in scaladoc. This is why there is a new flag called -no-prefixes that disables the prefixes in front of types. Btw, it also fixes the notorious "booleanValue: This member is added by an implicit conversion from Boolean to Boolean ...". That's now java.lang.Boolean, so it becomes clear. Conflicts: src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala --- build.xml | 38 +++- src/compiler/scala/tools/ant/Scaladoc.scala | 9 + src/compiler/scala/tools/nsc/doc/DocFactory.scala | 1 + src/compiler/scala/tools/nsc/doc/Settings.scala | 8 +- .../html/page/diagram/DotDiagramGenerator.scala | 8 +- .../nsc/doc/html/page/diagram/DotRunner.scala | 9 +- .../scala/tools/nsc/doc/model/Entity.scala | 9 +- .../scala/tools/nsc/doc/model/ModelFactory.scala | 196 ++++--------------- .../doc/model/ModelFactoryImplicitSupport.scala | 7 +- .../nsc/doc/model/ModelFactoryTypeSupport.scala | 215 +++++++++++++++++++++ .../tools/nsc/doc/model/diagram/Diagram.scala | 8 +- .../nsc/doc/model/diagram/DiagramFactory.scala | 33 ++-- test/scaladoc/resources/SI-4360.scala | 42 ++++ test/scaladoc/resources/implicits-scopes-res.scala | 2 +- test/scaladoc/resources/package-object-res.scala | 2 +- test/scaladoc/run/SI-3314.scala | 14 +- test/scaladoc/run/SI-4360.check | 1 + test/scaladoc/run/SI-4360.scala | 48 +++++ test/scaladoc/run/implicits-scopes.scala | 6 +- test/scaladoc/scalacheck/CommentFactoryTest.scala | 4 +- 20 files changed, 439 insertions(+), 221 deletions(-) create mode 100644 src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala create mode 100644 test/scaladoc/resources/SI-4360.scala create mode 100644 test/scaladoc/run/SI-4360.check create mode 100644 test/scaladoc/run/SI-4360.scala (limited to 'src') diff --git a/build.xml b/build.xml index 8fa1b9cd76..b5db4ab4f4 100644 --- a/build.xml +++ b/build.xml @@ -2082,8 +2082,9 @@ DOCUMENTATION - + + @@ -2111,7 +2112,10 @@ DOCUMENTATION classpathref="pack.classpath" addparams="${scalac.args.all}" docRootContent="${src.dir}/library/rootdoc.txt" - implicits="on" diagrams="on" rawOutput="${scaladoc.raw.output}"> + implicits="on" + diagrams="on" + rawOutput="${scaladoc.raw.output}" + noPrefixes="${scaladoc.no.prefixes}"> @@ -2195,7 +2199,10 @@ DOCUMENTATION srcdir="${src.dir}/compiler" docRootContent="${src.dir}/compiler/rootdoc.txt" addparams="${scalac.args.all}" - implicits="on" diagrams="on" rawOutput="${scaladoc.raw.output}"> + implicits="on" + diagrams="on" + rawOutput="${scaladoc.raw.output}" + noPrefixes="${scaladoc.no.prefixes}"> @@ -2217,7 +2224,10 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/jline/src/main/java" addparams="${scalac.args.all}" - implicits="on" diagrams="on" rawOutput="${scaladoc.raw.output}"> + implicits="on" + diagrams="on" + rawOutput="${scaladoc.raw.output}" + noPrefixes="${scaladoc.no.prefixes}"> @@ -2241,7 +2251,10 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/scalap" addparams="${scalac.args.all}" - implicits="on" diagrams="on" rawOutput="${scaladoc.raw.output}"> + implicits="on" + diagrams="on" + rawOutput="${scaladoc.raw.output}" + noPrefixes="${scaladoc.no.prefixes}"> @@ -2263,7 +2276,10 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/partest" addparams="${scalac.args.all}" - implicits="on" diagrams="on" rawOutput="${scaladoc.raw.output}"> + implicits="on" + diagrams="on" + rawOutput="${scaladoc.raw.output}" + noPrefixes="${scaladoc.no.prefixes}"> @@ -2285,7 +2301,10 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/continuations/plugin" addparams="${scalac.args.all}" - implicits="on" diagrams="on" rawOutput="${scaladoc.raw.output}"> + implicits="on" + diagrams="on" + rawOutput="${scaladoc.raw.output}" + noPrefixes="${scaladoc.no.prefixes}"> @@ -2307,7 +2326,10 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/actors-migration" addparams="${scalac.args.all}" - implicits="on" diagrams="on" rawOutput="${scaladoc.raw.output}"> + implicits="on" + diagrams="on" + rawOutput="${scaladoc.raw.output}" + noPrefixes="${scaladoc.no.prefixes}"> diff --git a/src/compiler/scala/tools/ant/Scaladoc.scala b/src/compiler/scala/tools/ant/Scaladoc.scala index 2cada92c1e..9aa2f6f921 100644 --- a/src/compiler/scala/tools/ant/Scaladoc.scala +++ b/src/compiler/scala/tools/ant/Scaladoc.scala @@ -153,6 +153,8 @@ class Scaladoc extends ScalaMatchingTask { /** Instruct the scaladoc to produce textual ouput from html pages, for easy diff-ing */ private var docRawOutput: Boolean = false + /** Instruct the scaladoc not to generate prefixes */ + private var docNoPrefixes: Boolean = false /*============================================================================*\ ** Properties setters ** @@ -427,6 +429,12 @@ class Scaladoc extends ScalaMatchingTask { def setRawOutput(input: String) = docRawOutput = Flag.getBooleanValue(input, "rawOutput") + /** Set the `noPrefixes` bit to prevent Scaladoc from generating prefixes in + * front of types -- may lead to confusion, but significantly speeds up the generation. + * @param input One of the flags `yes/no` or `on/off`. Default if no/off. */ + def setNoPrefixes(input: String) = + docNoPrefixes = Flag.getBooleanValue(input, "noPrefixes") + /*============================================================================*\ ** Properties getters ** \*============================================================================*/ @@ -625,6 +633,7 @@ class Scaladoc extends ScalaMatchingTask { docSettings.docDiagrams.value = docDiagrams docSettings.docDiagramsDebug.value = docDiagramsDebug docSettings.docRawOutput.value = docRawOutput + docSettings.docNoPrefixes.value = docNoPrefixes if(!docDiagramsDotPath.isEmpty) docSettings.docDiagramsDotPath.value = docDiagramsDotPath.get if (!docgenerator.isEmpty) docSettings.docgenerator.value = docgenerator.get diff --git a/src/compiler/scala/tools/nsc/doc/DocFactory.scala b/src/compiler/scala/tools/nsc/doc/DocFactory.scala index 3c92c3b4b6..964227a6a5 100644 --- a/src/compiler/scala/tools/nsc/doc/DocFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/DocFactory.scala @@ -81,6 +81,7 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor new { override val global: compiler.type = compiler } with model.ModelFactory(compiler, settings) with model.ModelFactoryImplicitSupport + with model.ModelFactoryTypeSupport with model.diagram.DiagramFactory with model.comment.CommentFactory with model.TreeFactory { diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala index 31e49131f6..c7bdf74ebd 100644 --- a/src/compiler/scala/tools/nsc/doc/Settings.scala +++ b/src/compiler/scala/tools/nsc/doc/Settings.scala @@ -166,6 +166,11 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) "For each html file, create another .html.raw file containing only the text. (can be used for quickly diffing two scaladoc outputs)" ) + val docNoPrefixes = BooleanSetting ( + "-no-prefixes", + "Prevents generating prefixes in types, possibly creating ambiguous references, but significantly speeding up scaladoc." + ) + // Somewhere slightly before r18708 scaladoc stopped building unless the // self-type check was suppressed. I hijacked the slotted-for-removal-anyway // suppress-vt-warnings option and renamed it for this purpose. @@ -177,7 +182,8 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) docDiagrams, docDiagramsDebug, docDiagramsDotPath, docDiagramsDotTimeout, docDiagramsDotRestart, docImplicits, docImplicitsDebug, docImplicitsShowAll, - docDiagramsMaxNormalClasses, docDiagramsMaxImplicitClasses + docDiagramsMaxNormalClasses, docDiagramsMaxImplicitClasses, + docNoPrefixes ) val isScaladocSpecific: String => Boolean = scaladocSpecific map (_.name) 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 59560befc9..f3454f71b8 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 @@ -86,22 +86,22 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { // them by on node with a corresponding tooltip superClasses = if (_superClasses.length > settings.docDiagramsMaxNormalClasses.value) { val superClassesTooltip = Some(limitSize(_superClasses.map(_.tpe.name).mkString(", "))) - List(NormalNode(textTypeEntity(_superClasses.length + MultiSuffix), None, superClassesTooltip)) + List(NormalNode(textTypeEntity(_superClasses.length + MultiSuffix), None)(superClassesTooltip)) } else _superClasses subClasses = if (_subClasses.length > settings.docDiagramsMaxNormalClasses.value) { val subClassesTooltip = Some(limitSize(_subClasses.map(_.tpe.name).mkString(", "))) - List(NormalNode(textTypeEntity(_subClasses.length + MultiSuffix), None, subClassesTooltip)) + List(NormalNode(textTypeEntity(_subClasses.length + MultiSuffix), None)(subClassesTooltip)) } else _subClasses incomingImplicits = if (_incomingImplicits.length > settings.docDiagramsMaxImplicitClasses.value) { val incomingImplicitsTooltip = Some(limitSize(_incomingImplicits.map(_.tpe.name).mkString(", "))) - List(ImplicitNode(textTypeEntity(_incomingImplicits.length + MultiSuffix), None, incomingImplicitsTooltip)) + List(ImplicitNode(textTypeEntity(_incomingImplicits.length + MultiSuffix), None)(incomingImplicitsTooltip)) } else _incomingImplicits outgoingImplicits = if (_outgoingImplicits.length > settings.docDiagramsMaxImplicitClasses.value) { val outgoingImplicitsTooltip = Some(limitSize(_outgoingImplicits.map(_.tpe.name).mkString(", "))) - List(ImplicitNode(textTypeEntity(_outgoingImplicits.length + MultiSuffix), None, outgoingImplicitsTooltip)) + List(ImplicitNode(textTypeEntity(_outgoingImplicits.length + MultiSuffix), None)(outgoingImplicitsTooltip)) } else _outgoingImplicits thisNode = _thisNode diff --git a/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotRunner.scala b/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotRunner.scala index 37600fa908..adfeb3b012 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotRunner.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotRunner.scala @@ -28,7 +28,7 @@ class DotRunner(settings: doc.Settings) { if (dotProcess == null) { if (dotRestarts < settings.docDiagramsDotRestart.value) { if (dotRestarts != 0) - settings.printMsg("A new graphviz dot process will be created...\n") + settings.printMsg("Graphviz will be restarted...\n") dotRestarts += 1 dotProcess = new DotProcess(settings) } else @@ -145,9 +145,10 @@ class DotProcess(settings: doc.Settings) { settings.printMsg("**********************************************************************") } else { // we shouldn't just sit there for 50s not reporting anything, no? - settings.printMsg("Graphviz dot encountered an error when generating the diagram for") - settings.printMsg(templateName + ". Use the " + settings.docDiagramsDebug.name + " flag") - settings.printMsg("for more information.") + settings.printMsg("Graphviz dot encountered an error when generating the diagram for:") + settings.printMsg(templateName) + settings.printMsg("These are usually spurious errors, but if you notice a persistant error on") + settings.printMsg("a diagram, please use the " + settings.docDiagramsDebug.name + " flag and report a bug with the output.") } } } diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index 4ab77b356b..41ba95e072 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -96,9 +96,6 @@ trait TemplateEntity extends Entity { /** The self-type of this template, if it differs from the template type. */ def selfType : Option[TypeEntity] - - /** The type of this entity, with type members */ - def ownType: TypeEntity } @@ -206,7 +203,8 @@ trait HigherKinded { /** 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 { - def kind = "" + def kind = "" + //def kind = "(not documented) template" } /** An inherited template that was not documented in its original owner - example: @@ -214,7 +212,8 @@ trait NoDocTemplate extends TemplateEntity { * in the source: trait U extends T -- C appears in U as a NoDocTemplateMemberImpl * -- that is, U has a member for it but C doesn't get its own page */ trait NoDocTemplateMemberEntity extends TemplateEntity with MemberEntity { - def kind = "" + def kind = "" + //def kind = "(not documented) member template" } /** A template (class, trait, object or package) for which documentation is available. Only templates for which diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 25b4a174ec..b7c4eed87d 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -19,7 +19,12 @@ import model.{ RootPackage => RootPackageEntity } /** This trait extracts all required information for documentation from compilation units */ class ModelFactory(val global: Global, val settings: doc.Settings) { - thisFactory: ModelFactory with ModelFactoryImplicitSupport with DiagramFactory with CommentFactory with TreeFactory => + thisFactory: ModelFactory + with ModelFactoryImplicitSupport + with ModelFactoryTypeSupport + with DiagramFactory + with CommentFactory + with TreeFactory => import global._ import definitions.{ ObjectClass, NothingClass, AnyClass, AnyValClass, AnyRefClass } @@ -32,7 +37,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { private var universe: Universe = null private def dbg(msg: String) = if (sys.props contains "scala.scaladoc.debug") println(msg) - private def closestPackage(sym: Symbol) = { + protected def closestPackage(sym: Symbol) = { if (sym.isPackage || sym.isPackageClass) sym else sym.enclosingPackage } @@ -63,7 +68,10 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { private val droppedPackages = mutable.Set[PackageImpl]() protected val docTemplatesCache = new mutable.LinkedHashMap[Symbol, DocTemplateImpl] protected val noDocTemplatesCache = new mutable.LinkedHashMap[Symbol, NoDocTemplateImpl] - protected var typeCache = new mutable.LinkedHashMap[Type, TypeEntity] + def packageDropped(tpl: DocTemplateImpl) = tpl match { + case p: PackageImpl => droppedPackages(p) + case _ => false + } def optimize(str: String): String = if (str.length < 16) str.intern else str @@ -95,7 +103,6 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def isObject = sym.isModule && !sym.isPackage def isCaseClass = sym.isCaseClass def isRootPackage = false - def ownType = makeType(sym.tpe, this) def selfType = if (sym.thisSym eq sym) None else Some(makeType(sym.thisSym.typeOfThis, this)) } @@ -338,14 +345,14 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def directSubClasses = allSubClasses.filter(_.parentTypes.map(_._1).contains(this)) /* Implcitly convertible class cache */ - private var implicitlyConvertibleClassesCache: mutable.ListBuffer[(DocTemplateEntity, ImplicitConversionImpl)] = null - def registerImplicitlyConvertibleClass(dtpl: DocTemplateEntity, conv: ImplicitConversionImpl): Unit = { + private var implicitlyConvertibleClassesCache: mutable.ListBuffer[(DocTemplateImpl, ImplicitConversionImpl)] = null + def registerImplicitlyConvertibleClass(dtpl: DocTemplateImpl, conv: ImplicitConversionImpl): Unit = { if (implicitlyConvertibleClassesCache == null) - implicitlyConvertibleClassesCache = mutable.ListBuffer[(DocTemplateEntity, ImplicitConversionImpl)]() + implicitlyConvertibleClassesCache = mutable.ListBuffer[(DocTemplateImpl, ImplicitConversionImpl)]() implicitlyConvertibleClassesCache += ((dtpl, conv)) } - def incomingImplicitlyConvertedClasses: List[(DocTemplateEntity, ImplicitConversionImpl)] = + def incomingImplicitlyConvertedClasses: List[(DocTemplateImpl, ImplicitConversionImpl)] = if (implicitlyConvertibleClassesCache == null) List() else @@ -408,7 +415,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { conv.targetTypeComponents map { case pair@(template, tpe) => template match { - case d: DocTemplateImpl => d.registerImplicitlyConvertibleClass(this, conv) + case d: DocTemplateImpl if (d != this) => d.registerImplicitlyConvertibleClass(this, conv) case _ => // nothing } (pair._1, pair._2, conv) @@ -508,6 +515,8 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { normalizeTemplate(aSym.owner) case _ if aSym.isModuleClass => normalizeTemplate(aSym.sourceModule) + // case t: ThisType => + // t. case _ => aSym } @@ -737,12 +746,12 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def findTemplate(query: String): Option[DocTemplateImpl] = { assert(modelFinished) - docTemplatesCache.values find { (tpl: TemplateImpl) => tpl.qualifiedName == query && !tpl.isObject } + docTemplatesCache.values find { (tpl: DocTemplateImpl) => tpl.qualifiedName == query && !packageDropped(tpl) && !tpl.isObject } } def findTemplateMaybe(aSym: Symbol): Option[DocTemplateImpl] = { assert(modelFinished) - docTemplatesCache.get(normalizeTemplate(aSym)) + docTemplatesCache.get(normalizeTemplate(aSym)).filterNot(packageDropped(_)) } def makeTemplate(aSym: Symbol): TemplateImpl = makeTemplate(aSym, None) @@ -890,158 +899,25 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { List((makeTemplate(aType.typeSymbol), makeType(aType, inTpl))) } - /** */ - def makeType(aType: Type, inTpl: TemplateImpl): TypeEntity = { - def templatePackage = closestPackage(inTpl.sym) - - def createTypeEntity = new TypeEntity { - private val nameBuffer = new StringBuilder - private var refBuffer = new immutable.TreeMap[Int, (LinkTo, Int)] - private def appendTypes0(types: List[Type], sep: String): Unit = types match { - case Nil => - case tp :: Nil => - appendType0(tp) - case tp :: tps => - appendType0(tp) - nameBuffer append sep - appendTypes0(tps, sep) - } - - private def appendType0(tpe: Type): Unit = tpe match { - /* Type refs */ - case tp: TypeRef if definitions.isFunctionType(tp) => - val args = tp.normalize.typeArgs - nameBuffer append '(' - appendTypes0(args.init, ", ") - nameBuffer append ") ⇒ " - appendType0(args.last) - case tp: TypeRef if definitions.isScalaRepeatedParamType(tp) => - appendType0(tp.args.head) - nameBuffer append '*' - case tp: TypeRef if definitions.isByNameParamType(tp) => - nameBuffer append "⇒ " - appendType0(tp.args.head) - case tp: TypeRef if definitions.isTupleType(tp) => - val args = tp.normalize.typeArgs - nameBuffer append '(' - appendTypes0(args, ", ") - nameBuffer append ')' - case TypeRef(pre, aSym, targs) => - val preSym = pre.widen.typeSymbol - // There's a work in progress here trying to deal with the - // places where undesirable prefixes are printed. - // ... - // If the prefix is something worthy of printing, see if the prefix type - // is in the same package as the enclosing template. If so, print it - // unqualified and they'll figure it out. - // - // val stripPrefixes = List(templatePackage.fullName + ".", "package.", "java.lang.") - // if (!preSym.printWithoutPrefix) { - // nameBuffer append stripPrefixes.foldLeft(pre.prefixString)(_ stripPrefix _) - // } - - // SI-3314/SI-4888: Classes, Traits and Types can be inherited from a template to another: - // class Enum { abstract class Value } - // class Day extends Enum { object Mon extends Value /*...*/ } - // ===> in such cases we have two options: - // (0) if there's no inheritance taking place (Enum#Value) we can link to the template directly - // (1) if we generate the doc template for Day, we can link to the correct member - // (2) if we don't generate the doc template, we should at least indicate the correct prefix in the tooltip - val bSym = normalizeTemplate(aSym) - val owner = - if ((preSym != NoSymbol) && /* it needs a prefix */ - (preSym != bSym.owner) && /* prefix is different from owner */ - // ((preSym != inTpl.sym) && /* prevent prefixes from being shown inside the defining class */ - // (preSym != inTpl.sym.moduleClass)) && /* or object */ - (aSym == bSym)) /* normalization doesn't play tricks on us */ - preSym - else - bSym.owner - - val bTpl = findTemplateMaybe(bSym) - val link = - if (owner == bSym.owner && bTpl.isDefined) - // (0) the owner's class is linked AND has a template - lovely - LinkToTpl(bTpl.get) - else { - val oTpl = findTemplateMaybe(owner) - val bMbr = oTpl.map(findMember(bSym, _)) - if (oTpl.isDefined && bMbr.isDefined && bMbr.get.isDefined) - // (1) the owner's class - LinkToMember(bMbr.get.get, oTpl.get) //ugh - else - // (2) if we still couldn't find the owner, make a noDocTemplate for everything (in the correct owner!) - LinkToTpl(makeTemplate(bSym, Some(makeTemplate(owner)))) - } - - // TODO: The name might include a prefix, take care of that! - val name = bSym.nameString - val pos0 = nameBuffer.length - refBuffer += pos0 -> ((link, name.length)) - nameBuffer append name - - // if (bSym.isNonClassType && bSym != AnyRefClass) { - // nameBuffer append bSym.decodedName - // } else { - // val tpl = makeTemplate(bSym) - // val pos0 = nameBuffer.length - // refBuffer += pos0 -> ((LinkToTpl(tpl), tpl.name.length)) - // nameBuffer append tpl.name - // } - - if (!targs.isEmpty) { - nameBuffer append '[' - appendTypes0(targs, ", ") - nameBuffer append ']' - } - /* Refined types */ - case RefinedType(parents, defs) => - val ignoreParents = Set[Symbol](AnyClass, ObjectClass) - val filtParents = parents filterNot (x => ignoreParents(x.typeSymbol)) match { - case Nil => parents - case ps => ps - } - appendTypes0(filtParents, " with ") - // XXX Still todo: properly printing refinements. - // Since I didn't know how to go about displaying a multi-line type, I went with - // printing single method refinements (which should be the most common) and printing - // the number of members if there are more. - defs.toList match { - case Nil => () - case x :: Nil => nameBuffer append (" { " + x.defString + " }") - case xs => nameBuffer append (" { ... /* %d definitions in type refinement */ }" format xs.size) - } - /* Eval-by-name types */ - case NullaryMethodType(result) => - nameBuffer append '⇒' - appendType0(result) - /* Polymorphic types */ - case PolyType(tparams, result) => assert(tparams.nonEmpty) -// throw new Error("Polymorphic type '" + tpe + "' cannot be printed as a type") - def typeParamsToString(tps: List[Symbol]): String = if (tps.isEmpty) "" else - tps.map{tparam => - tparam.varianceString + tparam.name + typeParamsToString(tparam.typeParams) - }.mkString("[", ", ", "]") - nameBuffer append typeParamsToString(tparams) - appendType0(result) - case tpen => - nameBuffer append tpen.toString + def makeQualifiedName(sym: Symbol, relativeTo: Option[Symbol] = None): String = { + val stop = if (relativeTo.isDefined) relativeTo.get.ownerChain.toSet else Set[Symbol]() + var sym1 = sym + var path = new StringBuilder() + // var path = List[Symbol]() + + while ((sym1 != NoSymbol) && (path.isEmpty || !stop(sym1))) { + val sym1Norm = normalizeTemplate(sym1) + if (!sym1.sourceModule.isPackageObject && sym1Norm != RootPackage) { + if (path.length != 0) + path.insert(0, ".") + path.insert(0, sym1Norm.nameString) + // path::= sym1Norm } - appendType0(aType) - val refEntity = refBuffer - val name = optimize(nameBuffer.toString) + sym1 = sym1.owner } - if (aType.isTrivial) - typeCache.get(aType) match { - case Some(typeEntity) => typeEntity - case None => - val typeEntity = createTypeEntity - typeCache += aType -> typeEntity - typeEntity - } - else - createTypeEntity + optimize(path.toString) + //path.mkString(".") } def normalizeOwner(aSym: Symbol): Symbol = diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala index 493ad3d831..ddcdf1cf5c 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala @@ -53,7 +53,7 @@ import model.{ RootPackage => RootPackageEntity } * TODO: Give an overview here */ trait ModelFactoryImplicitSupport { - thisFactory: ModelFactory with CommentFactory with TreeFactory => + thisFactory: ModelFactory with ModelFactoryTypeSupport with CommentFactory with TreeFactory => import global._ import global.analyzer._ @@ -329,11 +329,6 @@ trait ModelFactoryImplicitSupport { } } - def makeQualifiedName(sym: Symbol): String = { - val remove = Set[Symbol](RootPackage, RootClass, EmptyPackage, EmptyPackageClass) - sym.ownerChain.filterNot(remove.contains(_)).reverse.map(_.nameString).mkString(".") - } - /* ============== IMPLEMENTATION PROVIDING ENTITY TYPES ============== */ class ImplicitConversionImpl( diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala new file mode 100644 index 0000000000..2bc9f070b1 --- /dev/null +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala @@ -0,0 +1,215 @@ +/* NSC -- new Scala compiler -- Copyright 2007-2011 LAMP/EPFL */ + +package scala.tools.nsc +package doc +package model + +import comment._ + +import diagram._ + +import scala.collection._ +import scala.util.matching.Regex + +import symtab.Flags + +import io._ + +import model.{ RootPackage => RootPackageEntity } + +/** This trait extracts all required information for documentation from compilation units */ +trait ModelFactoryTypeSupport { + thisFactory: ModelFactory + with ModelFactoryImplicitSupport + with ModelFactoryTypeSupport + with DiagramFactory + with CommentFactory + with TreeFactory => + + import global._ + import definitions.{ ObjectClass, NothingClass, AnyClass, AnyValClass, AnyRefClass } + import rootMirror.{ RootPackage, RootClass, EmptyPackage } + + protected var typeCache = new mutable.LinkedHashMap[(Type, TemplateImpl), TypeEntity] + protected var typeCacheNoPrefix = new mutable.LinkedHashMap[Type, TypeEntity] + + /** */ + def makeType(aType: Type, inTpl: TemplateImpl): TypeEntity = { + def templatePackage = closestPackage(inTpl.sym) + + def createTypeEntity = new TypeEntity { + private var nameBuffer = new StringBuilder + private var refBuffer = new immutable.TreeMap[Int, (LinkTo, Int)] + private def appendTypes0(types: List[Type], sep: String): Unit = types match { + case Nil => + case tp :: Nil => + appendType0(tp) + case tp :: tps => + appendType0(tp) + nameBuffer append sep + appendTypes0(tps, sep) + } + + private def appendType0(tpe: Type): Unit = tpe match { + /* Type refs */ + case tp: TypeRef if definitions.isFunctionType(tp) => + val args = tp.normalize.typeArgs + nameBuffer append '(' + appendTypes0(args.init, ", ") + nameBuffer append ") ⇒ " + appendType0(args.last) + case tp: TypeRef if definitions.isScalaRepeatedParamType(tp) => + appendType0(tp.args.head) + nameBuffer append '*' + case tp: TypeRef if definitions.isByNameParamType(tp) => + nameBuffer append "⇒ " + appendType0(tp.args.head) + case tp: TypeRef if definitions.isTupleType(tp) => + val args = tp.normalize.typeArgs + nameBuffer append '(' + appendTypes0(args, ", ") + nameBuffer append ')' + case TypeRef(pre, aSym, targs) => + val preSym = pre.widen.typeSymbol + + // SI-3314/SI-4888: Classes, Traits and Types can be inherited from a template to another: + // class Enum { abstract class Value } + // class Day extends Enum { object Mon extends Value /*...*/ } + // ===> in such cases we have two options: + // (0) if there's no inheritance taking place (Enum#Value) we can link to the template directly + // (1) if we generate the doc template for Day, we can link to the correct member + // (2) if we don't generate the doc template, we should at least indicate the correct prefix in the tooltip + val bSym = normalizeTemplate(aSym) + val owner = + if ((preSym != NoSymbol) && /* it needs a prefix */ + (preSym != bSym.owner) && /* prefix is different from owner */ + // ((preSym != inTpl.sym) && /* prevent prefixes from being shown inside the defining class */ + // (preSym != inTpl.sym.moduleClass)) && /* or object */ + (aSym == bSym)) /* normalization doesn't play tricks on us */ + preSym + else + bSym.owner + + val bTpl = findTemplateMaybe(bSym) + val link = + if (owner == bSym.owner && bTpl.isDefined) + // (0) the owner's class is linked AND has a template - lovely + LinkToTpl(bTpl.get) + else { + val oTpl = findTemplateMaybe(owner) + val bMbr = oTpl.map(findMember(bSym, _)) + if (oTpl.isDefined && bMbr.isDefined && bMbr.get.isDefined) + // (1) the owner's class + LinkToMember(bMbr.get.get, oTpl.get) //ugh + else + // (2) if we still couldn't find the owner, make a noDocTemplate for everything (in the correct owner!) + LinkToTpl(makeTemplate(bSym, Some(makeTemplate(owner)))) + } + + // SI-4360 Showing prefixes when necessary + // We check whether there's any directly accessible type with the same name in the current template OR if the + // type is inherited from one template to another. There may be multiple symbols with the same name in scope, + // but we won't show the prefix if our symbol is among them, only if *it's not* -- that's equal to showing + // the prefix only for ambiguous references, not for overloaded ones. + def needsPrefix: Boolean = { + if (owner != bSym.owner && (normalizeTemplate(owner) != inTpl.sym)) + return true + + for (tpl <- inTpl.sym.ownerChain) { + tpl.info.member(bSym.name) match { + case NoSymbol => + // No syms with that name, look further inside the owner chain + case sym => + // Symbol found -- either the correct symbol, another one OR an overloaded alternative + if (sym == bSym) + return false + else sym.info match { + case OverloadedType(owner, alternatives) => + return alternatives.contains(bSym) + case _ => + return true + } + } + } + // if it's not found in the owner chain, we can safely leave out the prefix + false + } + + val prefix = + if (!settings.docNoPrefixes.value && needsPrefix && (bSym != AnyRefClass /* which we normalize */)) { + val qualifiedName = makeQualifiedName(owner, Some(inTpl.sym)) + if (qualifiedName != "") qualifiedName + "." else "" + } else "" + + //DEBUGGING: + //if (makeQualifiedName(bSym) == "pack1.A") println("needsPrefix(" + bSym + ", " + owner + ", " + inTpl.qualifiedName + ") => " + needsPrefix + " and prefix=" + prefix) + + val name = prefix + bSym.nameString + val pos0 = nameBuffer.length + refBuffer += pos0 -> ((link, name.length)) + nameBuffer append name + + if (!targs.isEmpty) { + nameBuffer append '[' + appendTypes0(targs, ", ") + nameBuffer append ']' + } + /* Refined types */ + case RefinedType(parents, defs) => + val ignoreParents = Set[Symbol](AnyClass, ObjectClass) + val filtParents = parents filterNot (x => ignoreParents(x.typeSymbol)) match { + case Nil => parents + case ps => ps + } + appendTypes0(filtParents, " with ") + // XXX Still todo: properly printing refinements. + // Since I didn't know how to go about displaying a multi-line type, I went with + // printing single method refinements (which should be the most common) and printing + // the number of members if there are more. + defs.toList match { + case Nil => () + case x :: Nil => nameBuffer append (" { " + x.defString + " }") + case xs => nameBuffer append (" { ... /* %d definitions in type refinement */ }" format xs.size) + } + /* Eval-by-name types */ + case NullaryMethodType(result) => + nameBuffer append '⇒' + appendType0(result) + /* Polymorphic types */ + case PolyType(tparams, result) => assert(tparams.nonEmpty) +// throw new Error("Polymorphic type '" + tpe + "' cannot be printed as a type") + def typeParamsToString(tps: List[Symbol]): String = if (tps.isEmpty) "" else + tps.map{tparam => + tparam.varianceString + tparam.name + typeParamsToString(tparam.typeParams) + }.mkString("[", ", ", "]") + nameBuffer append typeParamsToString(tparams) + appendType0(result) + case tpen => + nameBuffer append tpen.toString + } + appendType0(aType) + val refEntity = refBuffer + val name = optimize(nameBuffer.toString) + nameBuffer = null + } + + // SI-4360: Entity caching depends on both the type AND the template it's in, as the prefixes might change for the + // same type based on the template the type is shown in. + val cached = + if (!settings.docNoPrefixes.value) + typeCache.get((aType, inTpl)) + else + typeCacheNoPrefix.get(aType) + + cached match { + case Some(typeEntity) => typeEntity + case None => + val typeEntity = createTypeEntity + if (!settings.docNoPrefixes.value) + typeCache += (aType, inTpl) -> typeEntity + else + typeCacheNoPrefix += aType -> typeEntity + typeEntity + } + } +} \ No newline at end of file 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 2b804ca10f..902d5da240 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/Diagram.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/Diagram.scala @@ -98,20 +98,20 @@ object OtherNode { def unapply(n: Node): Option[(TypeEntity, Option[TemplateEn /** The node for the current class */ -case class ThisNode(tpe: TypeEntity, tpl: Option[TemplateEntity], tooltip: Option[String] = None) extends Node { override def isThisNode = true } +case class ThisNode(tpe: TypeEntity, tpl: Option[TemplateEntity])(val tooltip: Option[String] = None) extends Node { override def isThisNode = true } /** The usual node */ -case class NormalNode(tpe: TypeEntity, tpl: Option[TemplateEntity], tooltip: Option[String] = None) extends Node { override def isNormalNode = true } +case class NormalNode(tpe: TypeEntity, tpl: Option[TemplateEntity])(val tooltip: Option[String] = None) extends Node { override def isNormalNode = true } /** A class or trait the thisnode can be converted to by an implicit conversion * TODO: I think it makes more sense to use the tpe links to templates instead of the TemplateEntity for implicit nodes * since some implicit conversions convert the class to complex types that cannot be represented as a single tmeplate */ -case class ImplicitNode(tpe: TypeEntity, tpl: Option[TemplateEntity], tooltip: Option[String] = None) extends Node { override def isImplicitNode = true } +case class ImplicitNode(tpe: TypeEntity, tpl: Option[TemplateEntity])(val tooltip: Option[String] = None) extends Node { override def isImplicitNode = true } /** An outside node is shown in packages when a class from a different package makes it to the package diagram due to * its relation to a class in the template (see @contentDiagram hideInheritedNodes annotation) */ -case class OutsideNode(tpe: TypeEntity, tpl: Option[TemplateEntity], tooltip: Option[String] = None) extends Node { override def isOutsideNode = true } +case class OutsideNode(tpe: TypeEntity, tpl: Option[TemplateEntity])(val tooltip: Option[String] = None) extends Node { override def isOutsideNode = true } // Computing and offering node depth information 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 731801b143..d0b363854c 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala @@ -18,21 +18,14 @@ import scala.collection.immutable.SortedMap * @author Vlad Ureche */ trait DiagramFactory extends DiagramDirectiveParser { - this: ModelFactory with DiagramFactory with CommentFactory with TreeFactory => + this: ModelFactory with ModelFactoryTypeSupport with DiagramFactory with CommentFactory with TreeFactory => import this.global.definitions._ import this.global._ // the following can used for hardcoding different relations into the diagram, for bootstrapping purposes - lazy val AnyNode = normalNode(AnyClass) - lazy val AnyRefNode = normalNode(AnyRefClass) - lazy val AnyValNode = normalNode(AnyValClass) - lazy val NullNode = normalNode(NullClass) - lazy val NothingNode = normalNode(NothingClass) - def normalNode(sym: Symbol) = - NormalNode(makeTemplate(sym).ownType, Some(makeTemplate(sym))) def aggregationNode(text: String) = - NormalNode(new TypeEntity { val name = text; val refEntity = SortedMap[Int, (LinkTo, Int)]() }, None) + NormalNode(new TypeEntity { val name = text; val refEntity = SortedMap[Int, (LinkTo, Int)]() }, None)() /** Create the inheritance diagram for this template */ def makeInheritanceDiagram(tpl: DocTemplateImpl): Option[Diagram] = { @@ -52,31 +45,31 @@ trait DiagramFactory extends DiagramDirectiveParser { None else { // the main node - val thisNode = ThisNode(tpl.ownType, Some(tpl), Some(tpl.qualifiedName + " (this " + tpl.kind + ")")) + val thisNode = ThisNode(tpl.resultType, Some(tpl))(Some(tpl.qualifiedName + " (this " + tpl.kind + ")")) // superclasses var superclasses: List[Node] = tpl.parentTypes.collect { - case p: (TemplateEntity, TypeEntity) if !classExcluded(p._1) => NormalNode(p._2, Some(p._1)) + case p: (TemplateEntity, TypeEntity) if !classExcluded(p._1) => NormalNode(p._2, Some(p._1))() }.reverse // incoming implcit conversions lazy val incomingImplicitNodes = tpl.incomingImplicitlyConvertedClasses.map { case (incomingTpl, conv) => - ImplicitNode(incomingTpl.ownType, Some(incomingTpl), implicitTooltip(from=incomingTpl, to=tpl, conv=conv)) + ImplicitNode(makeType(incomingTpl.sym.tpe, tpl), Some(incomingTpl))(implicitTooltip(from=incomingTpl, to=tpl, conv=conv)) } // subclasses var subclasses: List[Node] = tpl.directSubClasses.flatMap { - case d: TemplateEntity if !classExcluded(d) => List(NormalNode(d.ownType, Some(d))) + case d: TemplateImpl if !classExcluded(d) => List(NormalNode(makeType(d.sym.tpe, tpl), Some(d))()) case _ => Nil }.sortBy(_.tpl.get.name)(implicitly[Ordering[String]].reverse) // outgoing implicit coversions lazy val outgoingImplicitNodes = tpl.outgoingImplicitlyConvertedClasses.map { case (outgoingTpl, outgoingType, conv) => - ImplicitNode(outgoingType, Some(outgoingTpl), implicitTooltip(from=tpl, to=tpl, conv=conv)) + ImplicitNode(outgoingType, Some(outgoingTpl))(implicitTooltip(from=tpl, to=tpl, conv=conv)) } // TODO: Everyone should be able to use the @{inherit,content}Diagram annotation to change the diagrams. @@ -149,7 +142,12 @@ trait DiagramFactory extends DiagramDirectiveParser { case _ => } - mapNodes += node -> (if (node.inTemplate == pack) NormalNode(node.ownType, Some(node)) else OutsideNode(node.ownType, Some(node))) + mapNodes += node -> ( + if (node.inTemplate == pack) + NormalNode(node.resultType, Some(node))() + else + OutsideNode(node.resultType, Some(node))() + ) } if (nodesShown.isEmpty) @@ -173,7 +171,10 @@ trait DiagramFactory extends DiagramDirectiveParser { val anyRefSubtypes = Nil val allAnyRefTypes = aggregationNode("All AnyRef subtypes") val nullTemplate = makeTemplate(NullClass) - ContentDiagram(allAnyRefTypes::nodes, (mapNodes(nullTemplate), allAnyRefTypes::anyRefSubtypes)::edges.filterNot(_._1.tpl == Some(nullTemplate))) + if (nullTemplate.isDocTemplate) + ContentDiagram(allAnyRefTypes::nodes, (mapNodes(nullTemplate), allAnyRefTypes::anyRefSubtypes)::edges.filterNot(_._1.tpl == Some(nullTemplate))) + else + ContentDiagram(nodes, edges) } else ContentDiagram(nodes, edges) diff --git a/test/scaladoc/resources/SI-4360.scala b/test/scaladoc/resources/SI-4360.scala new file mode 100644 index 0000000000..8e8b96afd5 --- /dev/null +++ b/test/scaladoc/resources/SI-4360.scala @@ -0,0 +1,42 @@ +package scala.test.scaladoc.prefix { + package pack1 { + + class A { + class Z + } + + class B extends A + + package a { + class C + } + + package b { + class C + } + + package c { + class C + + class L extends pack2.Z + + class TEST { + // test inherited classes + def fooCA(x: pack1.A#Z) = 1 + def fooCB(x: pack1.B#Z) = 1 + def fooCS(x: pack2.Z#Z) = 1 + def fooCL(x: L#Z) = 1 + // test in packages + def fooPA(x: pack1.a.C) = 1 + def fooPB(x: pack1.b.C) = 1 + def fooPC(x: pack1.c.C) = 1 + } + + class A extends pack1.A + } + } + + package pack2 { + class Z extends pack1.A + } +} \ No newline at end of file diff --git a/test/scaladoc/resources/implicits-scopes-res.scala b/test/scaladoc/resources/implicits-scopes-res.scala index aaeb43f95b..c675a645bd 100644 --- a/test/scaladoc/resources/implicits-scopes-res.scala +++ b/test/scaladoc/resources/implicits-scopes-res.scala @@ -22,7 +22,7 @@ package test2 { package classes { class A class B { def b = "" } - object test { /* (new A).b won't compile */ } + object test { (new A).b } } } diff --git a/test/scaladoc/resources/package-object-res.scala b/test/scaladoc/resources/package-object-res.scala index 17d5c0a499..f1f714dd1f 100644 --- a/test/scaladoc/resources/package-object-res.scala +++ b/test/scaladoc/resources/package-object-res.scala @@ -1,4 +1,4 @@ -/** This package have A and B. +/** This package has A and B. */ package test { trait A { def hi = "hello" } diff --git a/test/scaladoc/run/SI-3314.scala b/test/scaladoc/run/SI-3314.scala index 665223098a..3b5c658078 100644 --- a/test/scaladoc/run/SI-3314.scala +++ b/test/scaladoc/run/SI-3314.scala @@ -48,15 +48,15 @@ object Test extends ScaladocModelTest { val WeekDayInObject = test2._object("WeekDayObject")._member("WeekDay") val expected = List( - ("isWorkingDay1", "Value", ValueInClass), - ("isWorkingDay2", "Value", ValueInClass), - ("isWorkingDay3", "Value", ValueInTrait), - ("isWorkingDay4", "Value", ValueInTrait), - ("isWorkingDay5", "Value", ValueInObject), + ("isWorkingDay1", "WeekDayClass.Value", ValueInClass), + ("isWorkingDay2", "WeekDayClass.Value", ValueInClass), + ("isWorkingDay3", "WeekDayTrait.Value", ValueInTrait), + ("isWorkingDay4", "WeekDayTrait.Value", ValueInTrait), + ("isWorkingDay5", "WeekDayObject.Value", ValueInObject), ("isWorkingDay6", "WeekDay", WeekDayInObject), - ("isWorkingDay7", "Value", ValueInObject), + ("isWorkingDay7", "WeekDayObject.Value", ValueInObject), ("isWorkingDay8", "WeekDay", WeekDayInObject), - ("isWorkingDay9", "Value", ValueInObject)) + ("isWorkingDay9", "WeekDayObject.Value", ValueInObject)) for ((method, name, ref) <- expected) { assert(doc._method(method).valueParams(0)(0).resultType.name == name, diff --git a/test/scaladoc/run/SI-4360.check b/test/scaladoc/run/SI-4360.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-4360.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-4360.scala b/test/scaladoc/run/SI-4360.scala new file mode 100644 index 0000000000..3abc61c267 --- /dev/null +++ b/test/scaladoc/run/SI-4360.scala @@ -0,0 +1,48 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def resourceFile = "SI-4360.scala" + + // no need for special settings + def scaladocSettings = "" + + 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")._package("prefix") + + val TEST = base._package("pack1")._package("c")._class("TEST") + val fooCA = TEST._method("fooCA") + val fooCB = TEST._method("fooCB") + val fooCS = TEST._method("fooCS") + val fooCL = TEST._method("fooCL") + val fooPA = TEST._method("fooPA") + val fooPB = TEST._method("fooPB") + val fooPC = TEST._method("fooPC") + + val expected = List( + (fooCA, "Z", 1), + (fooCB, "B.Z", 1), + (fooCS, "pack2.Z.Z", 1), + (fooCL, "L.Z", 1), + (fooPA, "a.C", 1), + (fooPB, "b.C", 1), + (fooPC, "C", 1) + ) + + for ((method, name, refs) <- expected) { + assert(method.valueParams(0)(0).resultType.name == name, + method.valueParams(0)(0).resultType.name + " == " + name + " (in " + method.qualifiedName + ")") + assert(method.valueParams(0)(0).resultType.refEntity.size == refs, + method.valueParams(0)(0).resultType.refEntity.size + " == " + refs + " (in " + method.qualifiedName + ")") + } + + val A = base._package("pack1")._package("c")._class("A") + assert(A.linearizationTypes(0).name == "pack1.A", A.linearizationTypes(0).name + " == pack1.A") + assert(A.linearizationTypes(0).refEntity.size == 1, A.linearizationTypes(0).refEntity.size + " == 1") + } +} \ No newline at end of file diff --git a/test/scaladoc/run/implicits-scopes.scala b/test/scaladoc/run/implicits-scopes.scala index 7b9e80e148..d91deba326 100644 --- a/test/scaladoc/run/implicits-scopes.scala +++ b/test/scaladoc/run/implicits-scopes.scala @@ -24,7 +24,7 @@ object Test extends ScaladocModelTest { val test1 = base._package("test1") val A = test1._class("A") - conv = A._conversion(test1.qualifiedName + ".package.toB") // the .package means it's the package object + conv = A._conversion(test1.qualifiedName + ".toB") assert(conv.members.length == 1) assert(conv.constraints.length == 0) } @@ -36,7 +36,9 @@ object Test extends ScaladocModelTest { val classes = test2._package("classes") val A = classes._class("A") - assert(A._conversions(test2.qualifiedName + ".toB").isEmpty) + conv = A._conversion(test2.qualifiedName + ".toB") + assert(conv.members.length == 1) + assert(conv.constraints.length == 0) } //// test3 ///////////////////////////////////////////////////////////////////////////////////////////////////////////// diff --git a/test/scaladoc/scalacheck/CommentFactoryTest.scala b/test/scaladoc/scalacheck/CommentFactoryTest.scala index b576ba5544..b7869d5bf4 100644 --- a/test/scaladoc/scalacheck/CommentFactoryTest.scala +++ b/test/scaladoc/scalacheck/CommentFactoryTest.scala @@ -10,7 +10,7 @@ import scala.tools.nsc.doc.model.diagram._ class Factory(val g: Global, val s: doc.Settings) extends doc.model.ModelFactory(g, s) { - thisFactory: Factory with ModelFactoryImplicitSupport with DiagramFactory with CommentFactory with doc.model.TreeFactory => + thisFactory: Factory with ModelFactoryImplicitSupport with ModelFactoryTypeSupport with DiagramFactory with CommentFactory with doc.model.TreeFactory => def strip(c: Comment): Option[Inline] = { c.body match { @@ -31,7 +31,7 @@ object Test extends Properties("CommentFactory") { val settings = new doc.Settings((str: String) => {}) val reporter = new scala.tools.nsc.reporters.ConsoleReporter(settings) val g = new Global(settings, reporter) - (new Factory(g, settings) with ModelFactoryImplicitSupport with DiagramFactory with CommentFactory with doc.model.TreeFactory) + (new Factory(g, settings) with ModelFactoryImplicitSupport with ModelFactoryTypeSupport with DiagramFactory with CommentFactory with doc.model.TreeFactory) } def parse(src: String, dst: Inline) = { -- cgit v1.2.3 From 8d0ea747c240e4881c057a78cf2c90e69369ca4b Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Fri, 6 Jul 2012 02:17:01 +0200 Subject: Scaladoc minor fix: Typos in diagrams As suggested by Heather in pull request #816. --- src/compiler/scala/tools/nsc/doc/Settings.scala | 2 +- .../scala/tools/nsc/doc/html/page/diagram/DotRunner.scala | 2 +- src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala index c7bdf74ebd..aae88aa03e 100644 --- a/src/compiler/scala/tools/nsc/doc/Settings.scala +++ b/src/compiler/scala/tools/nsc/doc/Settings.scala @@ -147,7 +147,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) val docDiagramsDotTimeout = IntSetting( "-diagrams-dot-timeout", - "The timeout before the graphviz dot util is forecefully closed, in seconds (default: 10)", + "The timeout before the graphviz dot util is forcefully closed, in seconds (default: 10)", 10, None, _ => None diff --git a/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotRunner.scala b/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotRunner.scala index adfeb3b012..3040278290 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotRunner.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/diagram/DotRunner.scala @@ -46,7 +46,7 @@ class DotRunner(settings: doc.Settings) { if (dotRestarts == settings.docDiagramsDotRestart.value) { settings.printMsg("\n") settings.printMsg("**********************************************************************") - settings.printMsg("Diagrams will be disabled for this run beucause the graphviz dot tool") + settings.printMsg("Diagrams will be disabled for this run because the graphviz dot tool") settings.printMsg("has malfunctioned too many times. These scaladoc flags may help:") settings.printMsg("") val baseList = List(settings.docDiagramsDebug, diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index b7c4eed87d..2ce7927f42 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -367,7 +367,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { lazy val memberSyms = sym.info.members.filter(s => membersShouldDocument(s, this)) // the inherited templates (classes, traits or objects) - var memberSymsLazy = memberSyms.filter(t => templateShouldDocument(t, this) && !inOriginalOnwer(t, this)) + var memberSymsLazy = memberSyms.filter(t => templateShouldDocument(t, this) && !inOriginalOwner(t, this)) // the direct members (methods, values, vars, types and directly contained templates) var memberSymsEager = memberSyms.filter(!memberSymsLazy.contains(_)) // the members generated by the symbols in memberSymsEager @@ -611,7 +611,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { } else { // no class inheritance at this point - assert(inOriginalOnwer(bSym, inTpl)) + assert(inOriginalOwner(bSym, inTpl)) createDocTemplate(bSym, inTpl) } } @@ -716,7 +716,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { case _ => sys.error("'" + bSym + "' must be in a package") } - else if (!modelFinished && templateShouldDocument(bSym, inTpl) && inOriginalOnwer(bSym, inTpl)) + else if (!modelFinished && templateShouldDocument(bSym, inTpl) && inOriginalOwner(bSym, inTpl)) Some(modelCreation.createTemplate(bSym, inTpl)) else None @@ -945,7 +945,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { */ normalizeTemplate(aSym) - def inOriginalOnwer(aSym: Symbol, inTpl: TemplateImpl): Boolean = + def inOriginalOwner(aSym: Symbol, inTpl: TemplateImpl): Boolean = normalizeOwner(aSym.owner) == normalizeOwner(inTpl.sym) def templateShouldDocument(aSym: Symbol, inTpl: TemplateImpl): Boolean = @@ -953,7 +953,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { localShouldDocument(aSym) && !isEmptyJavaObject(aSym) && // either it's inside the original owner or we can document it later: - (!inOriginalOnwer(aSym, inTpl) || (aSym.isPackageClass || (aSym.sourceFile != null))) + (!inOriginalOwner(aSym, inTpl) || (aSym.isPackageClass || (aSym.sourceFile != null))) def membersShouldDocument(sym: Symbol, inTpl: TemplateImpl) = // pruning modules that shouldn't be documented -- cgit v1.2.3 From 929415a3f4d5d6261d10cc6d28720c5241716bae Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Sun, 8 Jul 2012 23:57:56 +0200 Subject: SI-4887 Link existentials in scaladoc Based on an inital patch by Nada Amin. Rewrote some of the code to compress it a bit. Also fixed a problem that was affecting the prefix printing for typerefs: type parameter and existentials won't get prefixes. While I can imagine cases where you'd want to see where they come from, you can always hover over them and see their origin. Also added support for pretty-printing ThisTypes, SuperTypes and SingleTypes (with links) --- .../nsc/doc/model/ModelFactoryTypeSupport.scala | 126 ++++++++++++++++++++- test/scaladoc/resources/SI-3314.scala | 15 +++ test/scaladoc/run/SI-3314.scala | 19 +++- test/scaladoc/run/SI-4887.check | 1 + test/scaladoc/run/SI-4887.scala | 46 ++++++++ 5 files changed, 200 insertions(+), 7 deletions(-) create mode 100644 test/scaladoc/run/SI-4887.check create mode 100644 test/scaladoc/run/SI-4887.scala (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala index 2bc9f070b1..0463ac0420 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala @@ -83,8 +83,6 @@ trait ModelFactoryTypeSupport { val owner = if ((preSym != NoSymbol) && /* it needs a prefix */ (preSym != bSym.owner) && /* prefix is different from owner */ - // ((preSym != inTpl.sym) && /* prevent prefixes from being shown inside the defining class */ - // (preSym != inTpl.sym.moduleClass)) && /* or object */ (aSym == bSym)) /* normalization doesn't play tricks on us */ preSym else @@ -112,8 +110,14 @@ trait ModelFactoryTypeSupport { // but we won't show the prefix if our symbol is among them, only if *it's not* -- that's equal to showing // the prefix only for ambiguous references, not for overloaded ones. def needsPrefix: Boolean = { - if (owner != bSym.owner && (normalizeTemplate(owner) != inTpl.sym)) + if ((owner != bSym.owner || preSym.isRefinementClass) && (normalizeTemplate(owner) != inTpl.sym)) return true + // don't get tricked into prefixng method type params and existentials: + // I tried several tricks BUT adding the method for which I'm creating the type => that simply won't scale, + // as ValueParams are independent of their parent member, and I really don't want to add this information to + // all terms, as we're already over the allowed memory footprint + if (aSym.isTypeParameterOrSkolem || aSym.isExistentiallyBound /* existential or existential skolem */) + return false for (tpl <- inTpl.sym.ownerChain) { tpl.info.member(bSym.name) match { @@ -137,8 +141,16 @@ trait ModelFactoryTypeSupport { val prefix = if (!settings.docNoPrefixes.value && needsPrefix && (bSym != AnyRefClass /* which we normalize */)) { - val qualifiedName = makeQualifiedName(owner, Some(inTpl.sym)) - if (qualifiedName != "") qualifiedName + "." else "" + if (!owner.isRefinementClass) { + val qName = makeQualifiedName(owner, Some(inTpl.sym)) + if (qName != "") qName + "." else "" + } + else { + nameBuffer append "(" + appendType0(pre) + nameBuffer append ")#" + "" // we already appended the prefix + } } else "" //DEBUGGING: @@ -175,15 +187,117 @@ trait ModelFactoryTypeSupport { case NullaryMethodType(result) => nameBuffer append '⇒' appendType0(result) + /* Polymorphic types */ case PolyType(tparams, result) => assert(tparams.nonEmpty) -// throw new Error("Polymorphic type '" + tpe + "' cannot be printed as a type") def typeParamsToString(tps: List[Symbol]): String = if (tps.isEmpty) "" else tps.map{tparam => tparam.varianceString + tparam.name + typeParamsToString(tparam.typeParams) }.mkString("[", ", ", "]") nameBuffer append typeParamsToString(tparams) appendType0(result) + + case et@ExistentialType(quantified, underlying) => + + def appendInfoStringReduced(sym: Symbol, tp: Type): Unit = { + if (sym.isType && !sym.isAliasType && !sym.isClass) { + tp match { + case PolyType(tparams, _) => + nameBuffer append "[" + appendTypes0(tparams.map(_.tpe), ", ") + nameBuffer append "]" + case _ => + } + tp.resultType match { + case rt @ TypeBounds(_, _) => + appendType0(rt) + case rt => + nameBuffer append " <: " + appendType0(rt) + } + } else { + // fallback to the Symbol infoString + nameBuffer append sym.infoString(tp) + } + } + + def appendClauses = { + nameBuffer append " forSome {" + var first = true + val qset = quantified.toSet + for (sym <- quantified) { + if (!first) { nameBuffer append ", " } else first = false + if (sym.isSingletonExistential) { + nameBuffer append "val " + nameBuffer append tpnme.dropSingletonName(sym.name) + nameBuffer append ": " + appendType0(dropSingletonType(sym.info.bounds.hi)) + } else { + if (sym.flagString != "") nameBuffer append (sym.flagString + " ") + if (sym.keyString != "") nameBuffer append (sym.keyString + " ") + nameBuffer append sym.varianceString + nameBuffer append sym.nameString + appendInfoStringReduced(sym, sym.info) + } + } + nameBuffer append "}" + } + + underlying match { + case TypeRef(pre, sym, args) if et.isRepresentableWithWildcards => + appendType0(typeRef(pre, sym, Nil)) + nameBuffer append "[" + var first = true + val qset = quantified.toSet + for (arg <- args) { + if (!first) { nameBuffer append ", " } else first = false + arg match { + case TypeRef(_, sym, _) if (qset contains sym) => + nameBuffer append "_" + appendInfoStringReduced(sym, sym.info) + case arg => + appendType0(arg) + } + } + nameBuffer append "]" + case MethodType(_, _) | NullaryMethodType(_) | PolyType(_, _) => + nameBuffer append "(" + appendType0(underlying) + nameBuffer append ")" + appendClauses + case _ => + appendType0(underlying) + appendClauses + } + + case tb@TypeBounds(lo, hi) => + if (tb.lo != TypeBounds.empty.lo) { + nameBuffer append " >: " + appendType0(lo) + } + if (tb.hi != TypeBounds.empty.hi) { + nameBuffer append " <: " + appendType0(hi) + } + // case tpen: ThisType | SingleType | SuperType => + // if (tpen.isInstanceOf[ThisType] && tpen.asInstanceOf[ThisType].sym.isEffectiveRoot) { + // appendType0 typeRef(NoPrefix, sym, Nil) + // } else { + // val underlying = + // val pre = underlying.typeSymbol.skipPackageObject + // if (pre.isOmittablePrefix) pre.fullName + ".type" + // else prefixString + "type" + case tpen@ThisType(sym) => + appendType0(typeRef(NoPrefix, sym, Nil)) + nameBuffer append ".this" + if (!tpen.underlying.typeSymbol.skipPackageObject.isOmittablePrefix) nameBuffer append ".type" + case tpen@SuperType(thistpe, supertpe) => + nameBuffer append "super[" + appendType0(supertpe) + nameBuffer append "]" + case tpen@SingleType(pre, sym) => + appendType0(typeRef(pre, sym, Nil)) + if (!tpen.underlying.typeSymbol.skipPackageObject.isOmittablePrefix) nameBuffer append ".type" case tpen => nameBuffer append tpen.toString } diff --git a/test/scaladoc/resources/SI-3314.scala b/test/scaladoc/resources/SI-3314.scala index e5773a4970..9e0afdce9d 100644 --- a/test/scaladoc/resources/SI-3314.scala +++ b/test/scaladoc/resources/SI-3314.scala @@ -1,5 +1,6 @@ package scala.test.scaladoc { + // testing inherited templates (Enum.Value is included in the source, thus is documented in scaladoc) package test1 { class Enum { abstract class Value @@ -12,6 +13,8 @@ package scala.test.scaladoc { } } + // testing inherited templates (scala.Enumeration.Value is taken from the library, thus is not + // documented in the scaladoc pages -- but should be inherited to make things clear!) package test2 { trait WeekDayTrait extends Enumeration { type WeekDay = Value @@ -67,4 +70,16 @@ package scala.test.scaladoc { def isWorkingDay9(d: WeekDayObject.Value) = ! (d == Sat || d == Sun) } } + + // testing type lambdas and useless prefixes (should be referenced as T instead of foo.T in the first example) + package test3 { + import language.higherKinds + object `package` { + trait T + trait A + trait X + def foo[T](x: T) = 7 + def bar[A](x: ({type Lambda[X] <: Either[A, X]})#Lambda[String]) = 5 + } + } } diff --git a/test/scaladoc/run/SI-3314.scala b/test/scaladoc/run/SI-3314.scala index 3b5c658078..fe220b08af 100644 --- a/test/scaladoc/run/SI-3314.scala +++ b/test/scaladoc/run/SI-3314.scala @@ -6,7 +6,7 @@ object Test extends ScaladocModelTest { override def resourceFile = "SI-3314.scala" // no need for special settings - def scaladocSettings = "" + def scaladocSettings = "-feature" def testModel(rootPackage: Package) = { // get the quick access implicit defs in scope (_package(s), _class(es), _trait(s), object(s) _method(s), _value(s)) @@ -15,6 +15,10 @@ object Test extends ScaladocModelTest { // 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") + + + // test1 + val test1 = base._package("test1") val test1Value = test1._class("Enum")._method("Value").resultType assert(test1Value.name == "Value", test1Value.name + " == Value") @@ -26,6 +30,9 @@ object Test extends ScaladocModelTest { assert(test1Constants.refEntity(0)._1 == LinkToMember(test1._object("Constants")._class("Value"), test1._object("Constants")), test1Constants.refEntity(0)._1 + " == LinkToMember(test1.Enum.Value)") + + // test2 + val test2 = base._package("test2") def testDefinition(doc: DocTemplateEntity) = { for (day <- List("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")) { @@ -70,5 +77,15 @@ object Test extends ScaladocModelTest { testUsage(test2._object("UserObject")) testUsage(test2._class("UserClass")) testUsage(test2._trait("UserTrait")) + + + // test3 + val test3 = base._package("test3") + val foo = test3._method("foo") + assert(foo.valueParams(0)(0).resultType.name == "T", + foo.valueParams(0)(0).resultType.name + " == T") + val bar = test3._method("bar") + assert(bar.valueParams(0)(0).resultType.name == "(AnyRef { type Lambda[X] <: Either[A,X] })#Lambda[String]", + bar.valueParams(0)(0).resultType.name + " == (AnyRef { type Lambda[X] <: Either[A,X] })#Lambda[String]") } } \ No newline at end of file diff --git a/test/scaladoc/run/SI-4887.check b/test/scaladoc/run/SI-4887.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-4887.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-4887.scala b/test/scaladoc/run/SI-4887.scala new file mode 100644 index 0000000000..af83344613 --- /dev/null +++ b/test/scaladoc/run/SI-4887.scala @@ -0,0 +1,46 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def code = """ + package scala.test.scaladoc.existentials { + import language.higherKinds + import language.existentials + + class X[T, U, V] + + trait TEST { + type T + type U + type A + def foo1(x: X[T, U, _]) = 3 + def foo2(x: X[Z[_], U, z.type] forSome {type Z[_] <: { def z: String }; val z: Z[_ <: Int]}) = 4 + def foo3(x: X[Z, Z, V] forSome { type Z <: T; type V <: T }) = 6 + } + } + """ + + // no need for special settings + def scaladocSettings = "-feature" + + 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._ + + val base = rootPackage._package("scala")._package("test")._package("scaladoc")._package("existentials") + val TEST = base._trait("TEST") + + val foo1 = TEST._method("foo1") + assert(foo1.valueParams(0)(0).resultType.name == "X[T, U, _]", + foo1.valueParams(0)(0).resultType.name + " == X[T, U, _]") + + val foo2 = TEST._method("foo2") + assert(foo2.valueParams(0)(0).resultType.name == "X[Z[_], U, _ <: [_]AnyRef { def z: String } with Singleton]", + foo2.valueParams(0)(0).resultType.name + " == X[Z[_], U, _ <: [_]AnyRef { def z: String } with Singleton]") + + val foo3 = TEST._method("foo3") + assert(foo3.valueParams(0)(0).resultType.name == "X[Z, Z, V] forSome {type Z <: T, type V <: T}", + foo3.valueParams(0)(0).resultType.name + " == X[Z, Z, V] forSome {type Z <: T, type V <: T}") + } +} \ No newline at end of file -- cgit v1.2.3 From dc70d1b7bd193ff42e9bed5d80f632cffb85a667 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Thu, 12 Jul 2012 00:31:25 +0200 Subject: SI-3695 SI-4224 SI-4497 SI-5079 scaladoc links Adds the ability to link to members, classes and objects in scaladoc. The links can now be either qualified names or relative names, they both work. See the test/scaladoc/resources/links.scala for a usage example. Also introduced -no-link-warnings scaladoc flag, in case the build output gets swamped with link warnings. --- src/compiler/scala/tools/nsc/doc/DocFactory.scala | 7 +- src/compiler/scala/tools/nsc/doc/Settings.scala | 7 +- .../scala/tools/nsc/doc/html/HtmlPage.scala | 45 ++--- .../scala/tools/nsc/doc/html/page/Template.scala | 23 +-- .../scala/tools/nsc/doc/model/Entity.scala | 19 +++ src/compiler/scala/tools/nsc/doc/model/Links.scala | 24 +++ .../scala/tools/nsc/doc/model/MemberLookup.scala | 185 +++++++++++++++++++++ .../scala/tools/nsc/doc/model/ModelFactory.scala | 67 +++++--- .../nsc/doc/model/ModelFactoryTypeSupport.scala | 4 +- .../scala/tools/nsc/doc/model/TypeEntity.scala | 5 - .../scala/tools/nsc/doc/model/comment/Body.scala | 7 +- .../nsc/doc/model/comment/CommentFactory.scala | 55 +++--- .../scala/tools/partest/ScaladocModelTest.scala | 13 +- test/scaladoc/resources/links.scala | 57 +++++++ test/scaladoc/run/SI-5235.scala | 4 +- test/scaladoc/run/links.check | 1 + test/scaladoc/run/links.scala | 28 ++++ test/scaladoc/scalacheck/CommentFactoryTest.scala | 16 +- 18 files changed, 459 insertions(+), 108 deletions(-) create mode 100644 src/compiler/scala/tools/nsc/doc/model/Links.scala create mode 100644 src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala create mode 100644 test/scaladoc/resources/links.scala create mode 100644 test/scaladoc/run/links.check create mode 100644 test/scaladoc/run/links.scala (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/DocFactory.scala b/src/compiler/scala/tools/nsc/doc/DocFactory.scala index 964227a6a5..9fccc57e44 100644 --- a/src/compiler/scala/tools/nsc/doc/DocFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/DocFactory.scala @@ -48,8 +48,8 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor /** Creates a scaladoc site for all symbols defined in this call's `source`, * as well as those defined in `sources` 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. */ + * @param source The list of paths (relative to the compiler's source path, + * or absolute) of files to document or the source code. */ def makeUniverse(source: Either[List[String], String]): Option[Universe] = { assert(settings.docformat.value == "html") source match { @@ -84,7 +84,8 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor with model.ModelFactoryTypeSupport with model.diagram.DiagramFactory with model.comment.CommentFactory - with model.TreeFactory { + with model.TreeFactory + with model.MemberLookup { override def templateShouldDocument(sym: compiler.Symbol, inTpl: TemplateImpl) = extraTemplatesToDocument(sym) || super.templateShouldDocument(sym, inTpl) } diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala index aae88aa03e..da478121e5 100644 --- a/src/compiler/scala/tools/nsc/doc/Settings.scala +++ b/src/compiler/scala/tools/nsc/doc/Settings.scala @@ -171,6 +171,11 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) "Prevents generating prefixes in types, possibly creating ambiguous references, but significantly speeding up scaladoc." ) + val docNoLinkWarnings = BooleanSetting ( + "-no-link-warnings", + "Avoid warnings for ambiguous and incorrect links." + ) + // Somewhere slightly before r18708 scaladoc stopped building unless the // self-type check was suppressed. I hijacked the slotted-for-removal-anyway // suppress-vt-warnings option and renamed it for this purpose. @@ -183,7 +188,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) docDiagramsDotTimeout, docDiagramsDotRestart, docImplicits, docImplicitsDebug, docImplicitsShowAll, docDiagramsMaxNormalClasses, docDiagramsMaxImplicitClasses, - docNoPrefixes + docNoPrefixes, docNoLinkWarnings, docRawOutput ) val isScaladocSpecific: String => Boolean = scaladocSpecific map (_.name) diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala index af5e90083e..226ed49aca 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala @@ -122,17 +122,30 @@ abstract class HtmlPage extends Page { thisPage => case Text(text) => xml.Text(text) case Summary(in) => inlineToHtml(in) case HtmlTag(tag) => xml.Unparsed(tag) - case EntityLink(target, template) => template() match { - case Some(tpl) => - templateToHtml(tpl) - case None => - xml.Text(target) - } + case EntityLink(target, link) => linkToHtml(target, link, true) + } + + def linkToHtml(text: Inline, link: LinkTo, hasLinks: Boolean) = link match { + case LinkToTpl(dtpl) => + if (hasLinks) + { inlineToHtml(text) } + else + { inlineToHtml(text) } + case LinkToMember(mbr, inTpl) => + if (hasLinks) + { inlineToHtml(text) } + else + { inlineToHtml(text) } + case Tooltip(tooltip) => + { inlineToHtml(text) } + // TODO: add case LinkToExternal here + case NoLink => + inlineToHtml(text) } def typeToHtml(tpes: List[model.TypeEntity], hasLinks: Boolean): NodeSeq = tpes match { case Nil => - sys.error("Internal Scaladoc error") + NodeSeq.Empty case List(tpe) => typeToHtml(tpe, hasLinks) case tpe :: rest => @@ -153,21 +166,9 @@ abstract class HtmlPage extends Page { thisPage => } } def toLinksIn(inPos: Int, starts: List[Int]): NodeSeq = { - val (tpl, width) = tpe.refEntity(inPos) - (tpl match { - case LinkToTpl(dtpl:DocTemplateEntity) if hasLinks => - { - string.slice(inPos, inPos + width) - } - case LinkToTpl(tpl) => - { string.slice(inPos, inPos + width) } - case LinkToMember(mbr, inTpl) if hasLinks => - { - string.slice(inPos, inPos + width) - } - case LinkToMember(mbr, inTpl) => - { string.slice(inPos, inPos + width) } - }) ++ toLinksOut(inPos + width, starts.tail) + val (link, width) = tpe.refEntity(inPos) + val text = comment.Text(string.slice(inPos, inPos + width)) + linkToHtml(text, link, hasLinks) ++ toLinksOut(inPos + width, starts.tail) } if (hasLinks) toLinksOut(0, tpe.refEntity.keySet.toList) 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 bba838ddcf..cfd50db99f 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -64,7 +64,7 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp nonAbsValueMembers partition (_.deprecation.isDefined) val (concValueMembers, shadowedImplicitMembers) = - nonDeprValueMembers partition (!Template.isShadowedOrAmbiguousImplicit(_)) + nonDeprValueMembers partition (!_.isShadowedOrAmbiguousImplicit) val typeMembers = tpl.abstractTypes ++ tpl.aliasTypes ++ tpl.templates.filter(x => x.isTrait || x.isClass) sorted @@ -387,7 +387,7 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp { constraintText } } ++ { - if (Template.isShadowedOrAmbiguousImplicit(mbr)) { + if (mbr.isShadowedOrAmbiguousImplicit) { // These are the members that are shadowing or ambiguating the current implicit // see ImplicitMemberShadowing trait for more information val shadowingSuggestion = { @@ -402,10 +402,10 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp } val shadowingWarning: NodeSeq = - if (Template.isShadowedImplicit(mbr)) + if (mbr.isShadowedImplicit) xml.Text("This implicitly inherited member is shadowed by one or more members in this " + "class.") ++ shadowingSuggestion - else if (Template.isAmbiguousImplicit(mbr)) + else if (mbr.isAmbiguousImplicit) xml.Text("This implicitly inherited member is ambiguous. One or more implicitly " + "inherited members have similar signatures, so calling this member may produce an ambiguous " + "implicit conversion compiler error.") ++ shadowingSuggestion @@ -646,13 +646,13 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp case PrivateInTemplate(owner) if (owner == mbr.inTemplate) => Some(Paragraph(CText("private"))) case PrivateInTemplate(owner) => - Some(Paragraph(Chain(List(CText("private["), EntityLink(owner.qualifiedName, () => Some(owner)), CText("]"))))) + Some(Paragraph(Chain(List(CText("private["), EntityLink(comment.Text(owner.qualifiedName), LinkToTpl(owner)), CText("]"))))) case ProtectedInInstance() => Some(Paragraph(CText("protected[this]"))) case ProtectedInTemplate(owner) if (owner == mbr.inTemplate) => Some(Paragraph(CText("protected"))) case ProtectedInTemplate(owner) => - Some(Paragraph(Chain(List(CText("protected["), EntityLink(owner.qualifiedName, () => Some(owner)), CText("]"))))) + Some(Paragraph(Chain(List(CText("protected["), EntityLink(comment.Text(owner.qualifiedName), LinkToTpl(owner)), CText("]"))))) case Public() => None } @@ -669,8 +669,8 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp { val nameClass = - if (Template.isImplicit(mbr)) - if (Template.isShadowedOrAmbiguousImplicit(mbr)) + if (mbr.isImplicitlyInherited) + if (mbr.isShadowedOrAmbiguousImplicit) "implicit shadowed" else "implicit" @@ -934,12 +934,5 @@ object Template { /* Vlad: Lesson learned the hard way: don't put any stateful code that references the model here, * it won't be garbage collected and you'll end up filling the heap with garbage */ - def isImplicit(mbr: MemberEntity) = mbr.byConversion.isDefined - def isShadowedImplicit(mbr: MemberEntity): Boolean = - mbr.byConversion.map(_.source.implicitsShadowing.get(mbr).map(_.isShadowed).getOrElse(false)).getOrElse(false) - def isAmbiguousImplicit(mbr: MemberEntity): Boolean = - mbr.byConversion.map(_.source.implicitsShadowing.get(mbr).map(_.isAmbiguous).getOrElse(false)).getOrElse(false) - def isShadowedOrAmbiguousImplicit(mbr: MemberEntity) = isShadowedImplicit(mbr) || isAmbiguousImplicit(mbr) - def lowerFirstLetter(s: String) = if (s.length >= 1) s.substring(0,1).toLowerCase() + s.substring(1) else s } diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index 41ba95e072..42db408fee 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -56,6 +56,12 @@ trait Entity { /** Whether or not the template was defined in a package object */ def inPackageObject: Boolean + + /** Indicates whether this entity lives in the types namespace (classes, traits, abstract/alias types) */ + def isType: Boolean + + /** Indicates whether this entity lives in the terms namespace (objects, packages, methods, values) */ + def isTerm: Boolean } object Entity { @@ -183,6 +189,19 @@ trait MemberEntity extends Entity { /** The identity of this member, used for linking */ def signature: String + + /** Indicates whether the member is inherited by implicit conversion */ + def isImplicitlyInherited: Boolean + + /** Indicates whether there is another member with the same name in the template that will take precendence */ + def isShadowedImplicit: Boolean + + /** Indicates whether there are other implicitly inherited members that have similar signatures (and thus they all + * become ambiguous) */ + def isAmbiguousImplicit: Boolean + + /** Indicates whether the implicitly inherited member is shadowed or ambiguous in its template */ + def isShadowedOrAmbiguousImplicit: Boolean } object MemberEntity { diff --git a/src/compiler/scala/tools/nsc/doc/model/Links.scala b/src/compiler/scala/tools/nsc/doc/model/Links.scala new file mode 100644 index 0000000000..b76dee0f14 --- /dev/null +++ b/src/compiler/scala/tools/nsc/doc/model/Links.scala @@ -0,0 +1,24 @@ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + */ + +package scala.tools.nsc +package doc +package model + +import scala.collection._ + +abstract sealed class LinkTo +case class LinkToTpl(tpl: DocTemplateEntity) extends LinkTo +case class LinkToMember(mbr: MemberEntity, inTpl: DocTemplateEntity) extends LinkTo +case class Tooltip(name: String) extends LinkTo { def this(tpl: TemplateEntity) = this(tpl.qualifiedName) } +// case class LinkToExternal(name: String, url: String) extends LinkTo // for SI-191, whenever Manohar will have time +case object NoLink extends LinkTo // you should use Tooltip if you have a name from the user, this is only in case all fails + +object LinkToTpl { + // this makes it easier to create links + def apply(tpl: TemplateEntity) = tpl match { + case dtpl: DocTemplateEntity => new LinkToTpl(dtpl) + case ntpl: TemplateEntity => new Tooltip(ntpl.qualifiedName) + } +} diff --git a/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala b/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala new file mode 100644 index 0000000000..7b131c13ef --- /dev/null +++ b/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala @@ -0,0 +1,185 @@ +package scala.tools.nsc +package doc +package model + +import comment._ + +import scala.reflect.internal.util.FakePos //Position + +/** This trait extracts all required information for documentation from compilation units */ +trait MemberLookup { + thisFactory: ModelFactory => + + import global._ + + def memberLookup(pos: Position, query: String, inTplOpt: Option[DocTemplateImpl]): LinkTo = { + assert(modelFinished) + + var members = breakMembers(query) + //println(query + " => " + members) + + // (1) Lookup in the root package, as most of the links are qualified + var linkTo: List[LinkTo] = lookupInRootPackage(pos, members) + + // (2) Recursively go into each + if (inTplOpt.isDefined) { + var currentTpl = inTplOpt.get + while (currentTpl != null && !currentTpl.isRootPackage && (linkTo.isEmpty)) { + linkTo = lookupInTemplate(pos, members, currentTpl) + currentTpl = currentTpl.inTemplate + } + if (currentTpl == null) println("\n\n\n\n\nnull found in:" + inTplOpt + "\n\n\n\n\n\n\n\n") + } + + // (3) Look at external links + if (linkTo.isEmpty) { + // TODO: IF THIS IS THE ROOT PACKAGE, LOOK AT EXTERNAL LINKS + } + + // (4) if we still haven't found anything, create a tooltip, if we found too many, report + if (linkTo.isEmpty){ + if (!settings.docNoLinkWarnings.value) + reporter.warning(pos, "Could not find any member to link for \"" + query + "\".") + Tooltip(query) + } else { + if (linkTo.length > 1) { + + val chosen = + if (linkTo.exists(_.isInstanceOf[LinkToMember])) + linkTo.collect({case lm: LinkToMember => lm}).min(Ordering[MemberEntity].on[LinkToMember](_.mbr)) + else + linkTo.head + + def linkToString(link: LinkTo) = { + val description = + link match { + case lm@LinkToMember(mbr, inTpl) => " * " + mbr.kind + " \"" + mbr.signature + "\" in " + inTpl.kind + " " + inTpl.qualifiedName + case lt@LinkToTpl(tpl) => " * " + tpl.kind + " \"" + tpl.qualifiedName + "\"" + case other => " * " + other.toString + } + val chosenInfo = + if (link == chosen) + " [chosen]" + else + "" + description + chosenInfo + "\n" + } + if (!settings.docNoLinkWarnings.value) + reporter.warning(pos, + "The link target \"" + query + "\" is ambiguous. Several (possibly overloaded) members fit the target:\n" + + linkTo.map(link => linkToString(link)).mkString + + (if (MemberLookup.showExplanation) + "\n\n" + + "Quick crash course on using Scaladoc links\n" + + "==========================================\n" + + "Disambiguating terms and types: Prefix terms with '$' and types with '!' in case both names are in use:\n" + + " - [[scala.collection.immutable.List!.apply class List's apply method]] and\n" + + " - [[scala.collection.immutable.List$.apply object List's apply method]]\n" + + "Disambiguating overloaded members: If a term is overloaded, you can indicate the first part of its signature followed by *:\n" + + " - [[[scala.collection.immutable.List$.fill[A](Int)(⇒A):List[A]* Fill with a single parameter]]]\n" + + " - [[[scala.collection.immutable.List$.fill[A](Int,Int)(⇒A):List[List[A]]* Fill with a two parameters]]]\n" + + "Notes: \n" + + " - you can use any number of matching square brackets to avoid interference with the signature\n" + + " - you can use \\. to escape dots in prefixes (don't forget to use * at the end to match the signature!)\n" + + " - you can use \\# to escape hashes, otherwise they will be considered as delimiters, like dots.\n" + else "") + ) + chosen + } else + linkTo.head + } + } + + private abstract class SearchStrategy + private object BothTypeAndTerm extends SearchStrategy + private object OnlyType extends SearchStrategy + private object OnlyTerm extends SearchStrategy + + private def lookupInRootPackage(pos: Position, members: List[String]) = lookupInTemplate(pos, members, makeRootPackage) + + private def lookupInTemplate(pos: Position, members: List[String], inTpl: DocTemplateImpl): List[LinkTo] = { + // Maintaining compatibility with previous links is a bit tricky here: + // we have a preference for term names for all terms except for the last, where we prefer a class: + // How to do this: + // - at each step we do a DFS search with the prefered strategy + // - if the search doesn't return any members, we backtrack on the last decision + // * we look for terms with the last member's name + // * we look for types with the same name, all the way up + val result = members match { + case Nil => + Nil + case mbrName::Nil => + var members = lookupInTemplate(pos, mbrName, inTpl, OnlyType) + if (members.isEmpty) + members = lookupInTemplate(pos, mbrName, inTpl, OnlyTerm) + + members.map(_ match { + case tpl: DocTemplateEntity => LinkToTpl(tpl) + case mbr => LinkToMember(mbr, inTpl) + }) + + case tplName::rest => + + def completeSearch(mbrs: List[MemberImpl]) = + mbrs.collect({case d:DocTemplateImpl => d}).flatMap(tpl => lookupInTemplate(pos, rest, tpl)) + + var members = completeSearch(lookupInTemplate(pos, tplName, inTpl, OnlyTerm)) + if (members.isEmpty) + members = completeSearch(lookupInTemplate(pos, tplName, inTpl, OnlyType)) + + members + } + //println("lookupInTemplate(" + members + ", " + inTpl + ") => " + result) + result + } + + private def lookupInTemplate(pos: Position, member: String, inTpl: DocTemplateImpl, strategy: SearchStrategy): List[MemberImpl] = { + val name = member.stripSuffix("$").stripSuffix("!").stripSuffix("*") + val result = if (member.endsWith("$")) + inTpl.members.filter(mbr => (mbr.name == name) && (mbr.isTerm)) + else if (member.endsWith("!")) + inTpl.members.filter(mbr => (mbr.name == name) && (mbr.isType)) + else if (member.endsWith("*")) + inTpl.members.filter(mbr => (mbr.signature.startsWith(name))) + else { + if (strategy == BothTypeAndTerm) + inTpl.members.filter(_.name == name) + else if (strategy == OnlyType) + inTpl.members.filter(mbr => (mbr.name == name) && (mbr.isType)) + else if (strategy == OnlyTerm) + inTpl.members.filter(mbr => (mbr.name == name) && (mbr.isTerm)) + else + Nil + } + + //println("lookupInTemplate(" + member + ", " + inTpl + ") => " + result) + result + } + + private def breakMembers(query: String): List[String] = { + // Okay, how does this work? Well: you split on . but you don't want to split on \. => thus the ugly regex + // query.split((?<=[^\\\\])\\.).map(_.replaceAll("\\.")) + // The same code, just faster: + var members = List[String]() + var index = 0 + var last_index = 0 + val length = query.length + while (index < length) { + if ((query.charAt(index) == '.' || query.charAt(index) == '#') && + ((index == 0) || (query.charAt(index-1) != '\\'))) { + + members ::= query.substring(last_index, index).replaceAll("\\\\([#\\.])", "$1") + last_index = index + 1 + } + index += 1 + } + if (last_index < length) + members ::= query.substring(last_index, length).replaceAll("\\\\\\.", ".") + members.reverse + } +} + +object MemberLookup { + private[this] var _showExplanation = true + def showExplanation: Boolean = if (_showExplanation) { _showExplanation = false; true } else false +} \ No newline at end of file diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 2ce7927f42..2642551aa8 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -24,7 +24,8 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { with ModelFactoryTypeSupport with DiagramFactory with CommentFactory - with TreeFactory => + with TreeFactory + with MemberLookup => import global._ import definitions.{ ObjectClass, NothingClass, AnyClass, AnyValClass, AnyRefClass } @@ -92,6 +93,8 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def qualifiedName = name def annotations = sym.annotations.map(makeAnnotation) def inPackageObject: Boolean = sym.owner.isModuleClass && sym.owner.sourceModule.isPackageObject + def isType = sym.name.isTypeName + def isTerm = sym.name.isTermName } trait TemplateImpl extends EntityImpl with TemplateEntity { @@ -108,7 +111,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { abstract class MemberImpl(sym: Symbol, implConv: ImplicitConversionImpl, inTpl: DocTemplateImpl) extends EntityImpl(sym, inTpl) with MemberEntity { lazy val comment = { - val commentTpl = + val inRealTpl = /* Variable precendence order for implicitly added members: Take the variable defifinitions from ... * 1. the target of the implicit conversion * 2. the definition template (owner) @@ -121,7 +124,11 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { case _ => inTpl } } else inTpl - if (commentTpl != null) thisFactory.comment(sym, commentTpl) else None + val thisTpl = this match { + case d: DocTemplateImpl => Some(d) + case _ => None + } + if (inRealTpl != null) thisFactory.comment(sym, thisTpl, inRealTpl) else None } override def inTemplate = inTpl override def toRoot: List[MemberImpl] = this :: inTpl.toRoot @@ -167,9 +174,9 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def deprecation = if (sym.isDeprecated) Some((sym.deprecationMessage, sym.deprecationVersion) match { - case (Some(msg), Some(ver)) => parseWiki("''(Since version " + ver + ")'' " + msg, NoPosition) - case (Some(msg), None) => parseWiki(msg, NoPosition) - case (None, Some(ver)) => parseWiki("''(Since version " + ver + ")''", NoPosition) + case (Some(msg), Some(ver)) => parseWiki("''(Since version " + ver + ")'' " + msg, NoPosition, Some(inTpl)) + case (Some(msg), None) => parseWiki(msg, NoPosition, Some(inTpl)) + case (None, Some(ver)) => parseWiki("''(Since version " + ver + ")''", NoPosition, Some(inTpl)) case (None, None) => Body(Nil) }) else @@ -177,9 +184,9 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def migration = if(sym.hasMigrationAnnotation) Some((sym.migrationMessage, sym.migrationVersion) match { - case (Some(msg), Some(ver)) => parseWiki("''(Changed in version " + ver + ")'' " + msg, NoPosition) - case (Some(msg), None) => parseWiki(msg, NoPosition) - case (None, Some(ver)) => parseWiki("''(Changed in version " + ver + ")''", NoPosition) + case (Some(msg), Some(ver)) => parseWiki("''(Changed in version " + ver + ")'' " + msg, NoPosition, Some(inTpl)) + case (Some(msg), None) => parseWiki(msg, NoPosition, Some(inTpl)) + case (None, Some(ver)) => parseWiki("''(Changed in version " + ver + ")''", NoPosition, Some(inTpl)) case (None, None) => Body(Nil) }) else @@ -213,28 +220,34 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def byConversion = if (implConv ne null) Some(implConv) else None lazy val signature = { - val defParamsString = this match { + def defParams(mbr: Any): String = mbr match { case d: MemberEntity with Def => val paramLists: List[String] = - if (d.valueParams.isEmpty) Nil - else d.valueParams map (ps => ps map (_.resultType.name) mkString ("(",",",")")) - - val tParams = if (d.typeParams.isEmpty) "" else { - def boundsToString(hi: Option[TypeEntity], lo: Option[TypeEntity]): String = { - def bound0(bnd: Option[TypeEntity], pre: String): String = bnd match { - case None => "" - case Some(tpe) => pre ++ tpe.toString - } - bound0(hi, "<:") ++ bound0(lo, ">:") + if (d.valueParams.isEmpty) Nil + else d.valueParams map (ps => ps map (_.resultType.name) mkString ("(",",",")")) + paramLists.mkString + case _ => "" + } + + def tParams(mbr: Any): String = mbr match { + case hk: HigherKinded if !hk.typeParams.isEmpty => + def boundsToString(hi: Option[TypeEntity], lo: Option[TypeEntity]): String = { + def bound0(bnd: Option[TypeEntity], pre: String): String = bnd match { + case None => "" + case Some(tpe) => pre ++ tpe.toString } - "[" + d.typeParams.map(tp => tp.variance + tp.name + boundsToString(tp.hi, tp.lo)).mkString(", ") + "]" + bound0(hi, "<:") ++ bound0(lo, ">:") } - - tParams + paramLists.mkString + "[" + hk.typeParams.map(tp => tp.variance + tp.name + tParams(tp) + boundsToString(tp.hi, tp.lo)).mkString(", ") + "]" case _ => "" } - name + defParamsString +":"+ resultType.name + + (name + tParams(this) + defParams(this) +":"+ resultType.name).replaceAll("\\s","") // no spaces allowed, they break links } + def isImplicitlyInherited = { assert(modelFinished); byConversion.isDefined } + def isShadowedImplicit = isImplicitlyInherited && inTpl.implicitsShadowing.get(this).map(_.isShadowed).getOrElse(false) + def isAmbiguousImplicit = isImplicitlyInherited && inTpl.implicitsShadowing.get(this).map(_.isAmbiguous).getOrElse(false) + def isShadowedOrAmbiguousImplicit = isShadowedImplicit || isAmbiguousImplicit } /** A template that is not documented at all. The class is instantiated during lookups, to indicate that the class @@ -546,7 +559,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { import Streamable._ Path(settings.docRootContent.value) match { case f : File => { - val rootComment = closing(f.inputStream)(is => parse(slurp(is), "", NoPosition)) + val rootComment = closing(f.inputStream)(is => parse(slurp(is), "", NoPosition, Option(inTpl))) Some(rootComment) } case _ => None @@ -658,7 +671,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { if (bSym.isGetter && bSym.isLazy) Some(new NonTemplateMemberImpl(bSym, implConv, inTpl) with Val { override lazy val comment = // The analyser does not duplicate the lazy val's DocDef when it introduces its accessor. - thisFactory.comment(bSym.accessed, inTpl.asInstanceOf[DocTemplateImpl]) // This hack should be removed after analyser is fixed. + thisFactory.comment(bSym.accessed, None, inTpl.asInstanceOf[DocTemplateImpl]) // This hack should be removed after analyser is fixed. override def isLazyVal = true override def useCaseOf = _useCaseOf }) @@ -744,6 +757,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { inTpl.members.find(_.sym == aSym) } + @deprecated("2.10", "Use findLinkTarget instead!") def findTemplate(query: String): Option[DocTemplateImpl] = { assert(modelFinished) docTemplatesCache.values find { (tpl: DocTemplateImpl) => tpl.qualifiedName == query && !packageDropped(tpl) && !tpl.isObject } @@ -776,7 +790,6 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { } } - /** */ def makeAnnotation(annot: AnnotationInfo): Annotation = { val aSym = annot.symbol diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala index 0463ac0420..5efae3257c 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala @@ -100,8 +100,8 @@ trait ModelFactoryTypeSupport { // (1) the owner's class LinkToMember(bMbr.get.get, oTpl.get) //ugh else - // (2) if we still couldn't find the owner, make a noDocTemplate for everything (in the correct owner!) - LinkToTpl(makeTemplate(bSym, Some(makeTemplate(owner)))) + // (2) if we still couldn't find the owner, show a tooltip with the qualified name + Tooltip(makeQualifiedName(bSym)) } // SI-4360 Showing prefixes when necessary diff --git a/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala b/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala index a16e99bf06..643067cca5 100644 --- a/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/TypeEntity.scala @@ -9,10 +9,6 @@ package model import scala.collection._ -abstract sealed class LinkTo -case class LinkToTpl(tpl: TemplateEntity) extends LinkTo -case class LinkToMember(mbr: MemberEntity, inTpl: DocTemplateEntity) extends LinkTo - /** 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. */ @@ -28,5 +24,4 @@ abstract class TypeEntity { /** The human-readable representation of this type. */ override def toString = name - } diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala b/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala index ecc3273903..3ab8fc7805 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala @@ -44,7 +44,6 @@ final case class Body(blocks: Seq[Block]) { case inlines => Some(Chain(inlines)) } } - } /** A block-level element of text, such as a paragraph or code block. */ @@ -67,10 +66,14 @@ final case class Bold(text: Inline) extends Inline final case class Underline(text: Inline) extends Inline final case class Superscript(text: Inline) extends Inline final case class Subscript(text: Inline) extends Inline -final case class EntityLink(target: String, template: () => Option[TemplateEntity]) extends Inline final case class Link(target: String, title: Inline) extends Inline final case class Monospace(text: Inline) extends Inline final case class Text(text: String) extends Inline +abstract class EntityLink(val title: Inline) extends Inline { def link: LinkTo } +object EntityLink { + def apply(title: Inline, linkTo: LinkTo) = new EntityLink(title) { def link: LinkTo = linkTo} + def unapply(el: EntityLink): Option[(Inline, LinkTo)] = Some((el.title, el.link)) +} final case class HtmlTag(data: String) extends Inline { def canClose(open: HtmlTag) = { open.data.stripPrefix("<") == data.stripPrefix(" +trait CommentFactory { thisFactory: ModelFactory with CommentFactory with MemberLookup=> val global: Global import global.{ reporter, definitions } @@ -31,16 +31,16 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => protected val commentCache = mutable.HashMap.empty[(global.Symbol, TemplateImpl), Comment] def addCommentBody(sym: global.Symbol, inTpl: TemplateImpl, docStr: String, docPos: global.Position): global.Symbol = { - commentCache += (sym, inTpl) -> parse(docStr, docStr, docPos) + commentCache += (sym, inTpl) -> parse(docStr, docStr, docPos, None) sym } - def comment(sym: global.Symbol, inTpl: DocTemplateImpl): Option[Comment] = { + def comment(sym: global.Symbol, currentTpl: Option[DocTemplateImpl], inTpl: DocTemplateImpl): Option[Comment] = { val key = (sym, inTpl) if (commentCache isDefinedAt key) Some(commentCache(key)) else { - val c = defineComment(sym, inTpl) + val c = defineComment(sym, currentTpl, inTpl) if (c isDefined) commentCache += (sym, inTpl) -> c.get c } @@ -50,7 +50,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => * cases we have to give some `inTpl` comments (parent class for example) * to the comment of the symbol. * This function manages some of those cases : Param accessor and Primary constructor */ - def defineComment(sym: global.Symbol, inTpl: DocTemplateImpl):Option[Comment] = { + def defineComment(sym: global.Symbol, currentTpl: Option[DocTemplateImpl], inTpl: DocTemplateImpl):Option[Comment] = { //param accessor case // We just need the @param argument, we put it into the body @@ -87,7 +87,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => else { val rawComment = global.expandedDocComment(sym, inTpl.sym).trim if (rawComment != "") { - val c = parse(rawComment, global.rawDocComment(sym), global.docCommentPos(sym)) + val tplOpt = if (currentTpl.isDefined) currentTpl else Some(inTpl) + val c = parse(rawComment, global.rawDocComment(sym), global.docCommentPos(sym), tplOpt) Some(c) } else None @@ -225,7 +226,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => * @param comment The expanded comment string (including start and end markers) to be parsed. * @param src The raw comment source string. * @param pos The position of the comment in source. */ - protected def parse(comment: String, src: String, pos: Position): Comment = { + protected def parse(comment: String, src: String, pos: Position, inTplOpt: Option[DocTemplateImpl] = None): Comment = { + assert(!inTplOpt.isDefined || inTplOpt.get != null) /** The cleaned raw comment as a list of lines. Cleaning removes comment * start and end markers, line start markers and unnecessary whitespace. */ @@ -351,7 +353,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => val tagsWithoutDiagram = tags.filterNot(pair => pair._1 == inheritDiagramTag || pair._1 == contentDiagramTag) val bodyTags: mutable.Map[TagKey, List[Body]] = - mutable.Map(tagsWithoutDiagram mapValues {tag => tag map (parseWiki(_, pos))} toSeq: _*) + mutable.Map(tagsWithoutDiagram mapValues {tag => tag map (parseWiki(_, pos, inTplOpt))} toSeq: _*) def oneTag(key: SimpleTagKey): Option[Body] = ((bodyTags remove key): @unchecked) match { @@ -384,7 +386,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => } val com = createComment ( - body0 = Some(parseWiki(docBody.toString, pos)), + body0 = Some(parseWiki(docBody.toString, pos, inTplOpt)), authors0 = allTags(SimpleTagKey("author")), see0 = allTags(SimpleTagKey("see")), result0 = oneTag(SimpleTagKey("return")), @@ -420,8 +422,10 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => * - Removed start-of-line star and one whitespace afterwards (if present). * - Removed all end-of-line whitespace. * - Only `endOfLine` is used to mark line endings. */ - def parseWiki(string: String, pos: Position): Body = { - new WikiParser(string, pos).document() + def parseWiki(string: String, pos: Position, inTplOpt: Option[DocTemplateImpl]): Body = { + assert(!inTplOpt.isDefined || inTplOpt.get != null) + + new WikiParser(string, pos, inTplOpt).document() } /** TODO @@ -429,7 +433,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => * @author Ingo Maier * @author Manohar Jonnalagedda * @author Gilles Dubochet */ - protected final class WikiParser(val buffer: String, pos: Position) extends CharReader(buffer) { wiki => + protected final class WikiParser(val buffer: String, pos: Position, inTplOpt: Option[DocTemplateImpl]) extends CharReader(buffer) { wiki => + assert(!inTplOpt.isDefined || inTplOpt.get != null) var summaryParsed = false @@ -617,7 +622,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => else if (check(",,")) subscript() else if (check("[[")) link() else { - readUntil { char == safeTagMarker || check("''") || char == '`' || check("__") || char == '^' || check(",,") || check("[[") || isInlineEnd || checkParaEnded || char == endOfLine } + readUntil { char == safeTagMarker || check("''") || char == '`' || check("__") || char == '^' || check(",,") || check("[[") || check("{{") || isInlineEnd || checkParaEnded || char == endOfLine } Text(getRead()) } } @@ -719,29 +724,27 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => def link(): Inline = { val SchemeUri = """([^:]+:.*)""".r jump("[[") - readUntil { check("]]") || check(" ") } + var parens = 1 + readUntil { parens += 1; !check("[") } + getRead // clear the buffer + val start = "[" * parens + val stop = "]" * parens + //println("link with " + parens + " matching parens") + readUntil { check(stop) || check(" ") } val target = getRead() val title = - if (!check("]]")) Some({ + if (!check(stop)) Some({ jump(" ") - inline(check("]]")) + inline(check(stop)) }) else None - jump("]]") + jump(stop) (target, title) match { case (SchemeUri(uri), optTitle) => Link(uri, optTitle getOrElse Text(uri)) case (qualName, optTitle) => - optTitle foreach (text => reportError(pos, "entity link to " + qualName + " cannot have a custom title'" + text + "'")) - // XXX rather than warning here we should allow unqualified names - // to refer to members of the same package. The "package exists" - // exclusion is because [[scala]] is used in some scaladoc. - if (!qualName.contains(".") && !definitions.packageExists(qualName)) - reportError(pos, "entity link to " + qualName + " should be a fully qualified name") - - // move the template resolution as late as possible - EntityLink(qualName, () => findTemplate(qualName)) + new EntityLink(optTitle getOrElse Text(target)) { def link = memberLookup(pos, target, inTplOpt) } } } diff --git a/src/partest/scala/tools/partest/ScaladocModelTest.scala b/src/partest/scala/tools/partest/ScaladocModelTest.scala index c89dd2cb8f..fb93e98726 100644 --- a/src/partest/scala/tools/partest/ScaladocModelTest.scala +++ b/src/partest/scala/tools/partest/ScaladocModelTest.scala @@ -12,7 +12,7 @@ import scala.tools.nsc.util.CommandLineParser import scala.tools.nsc.doc.{Settings, DocFactory, Universe} import scala.tools.nsc.doc.model._ import scala.tools.nsc.reporters.ConsoleReporter -import scala.tools.nsc.doc.model.comment.Comment +import scala.tools.nsc.doc.model.comment._ /** A class for testing scaladoc model generation * - you need to specify the code in the `code` method @@ -165,10 +165,21 @@ abstract class ScaladocModelTest extends DirectTest { def extractCommentText(c: Comment) = { def extractText(body: Any): String = body match { case s: String => s + case s: Seq[_] => s.toList.map(extractText(_)).mkString case p: Product => p.productIterator.toList.map(extractText(_)).mkString case _ => "" } extractText(c.body) } + + def countLinks(c: Comment, p: EntityLink => Boolean) = { + def countLinks(body: Any): Int = body match { + case el: EntityLink if p(el) => 1 + case s: Seq[_] => s.toList.map(countLinks(_)).sum + case p: Product => p.productIterator.toList.map(countLinks(_)).sum + case _ => 0 + } + countLinks(c.body) + } } } diff --git a/test/scaladoc/resources/links.scala b/test/scaladoc/resources/links.scala new file mode 100644 index 0000000000..679d0b0dce --- /dev/null +++ b/test/scaladoc/resources/links.scala @@ -0,0 +1,57 @@ +// that would be: +// SI-5079 "Scaladoc can't link to an object (only a class or trait)" +// SI-4497 "Links in ScalaDoc - Spec and implementation unsufficient" +// SI-4224 "Wiki-links should support method targets" +// SI-3695 "support non-fully-qualified type links in scaladoc comments" +package scala.test.scaladoc.links { + import language.higherKinds + class C + + trait Target { + type T + type S = String + class C + def foo(i: Int) = 2 + def foo(s: String) = 3 + def foo[A[_]](x: A[String]) = 5 + def foo[A[_[_]]](x: A[List]) = 6 + val bar: Boolean + def baz(c: scala.test.scaladoc.links.C) = 7 + } + + object Target { + type T = Int => Int + type S = Int + class C + def foo(i: Int) = 2 + def foo(z: String) = 3 + def foo[A[_]](x: A[String]) = 5 + def foo[A[_[_]]](x: A[List]) = 6 + val bar: Boolean = false + val onlyInObject = 1 + def baz(c: scala.test.scaladoc.links.C) = 7 + } + + /** + * Links to the trait: + * - [[scala.test.scaladoc.links.Target!.T trait Target -> type T]] + * - [[test.scaladoc.links.Target!.S trait Target -> type S]] + * - [[scaladoc.links.Target!.foo(Int)* trait Target -> def foo]] + * - [[links.Target!.bar trait Target -> def bar]] + * - [[[[Target!.foo[A[_[_]]]* trait Target -> def foo with 3 nested tparams]]]] (should exercise nested parens) + * - [[Target$.T object Target -> type T]] + * - [[Target$.S object Target -> type S]] + * - [[Target$.foo(Str* object Target -> def foo]] + * - [[Target$.bar object Target -> def bar]] + * - [[[[Target$.foo[A[_[_]]]* trait Target -> def foo with 3 nested tparams]]]] (should exercise nested parens) + * - [[Target.onlyInObject object Target -> def foo]] (should find the object) + * - [[Target$.C object Target -> class C]] (should link directly to C, not as a member) + * - [[Target!.C trait Target -> class C]] (should link directly to C, not as a member) + * - [[Target$.baz(links\.C)* object Target -> def baz]] (should use dots in prefix) + * - [[Target!.baz(links\.C)* trait Target -> def baz]] (should use dots in prefix) + * - [[localMethod object TEST -> localMethod]] (should use the current template to resolve link instead of inTpl, that's the package) + */ + object TEST { + def localMethod = 3 + } +} diff --git a/test/scaladoc/run/SI-5235.scala b/test/scaladoc/run/SI-5235.scala index f0c6e1cf17..6295fc7786 100644 --- a/test/scaladoc/run/SI-5235.scala +++ b/test/scaladoc/run/SI-5235.scala @@ -79,8 +79,8 @@ object Test extends ScaladocModelTest { assert(mcReverseType.name == "MyCollection",mcReverseType.name + " == MyCollection") assert(gcReverseType.refEntity(0)._1 == LinkToTpl(GenericColl), gcReverse.qualifiedName + "'s return type has a link to " + GenericColl.qualifiedName) - assert(!scReverseType.refEntity(0)._1.asInstanceOf[LinkToTpl].tpl.isDocTemplate, - scReverse.qualifiedName + "'s return type does not have links") + assert(scReverseType.refEntity(0)._1 == Tooltip("BullSh"), + scReverseType.refEntity(0)._1 + " == Tooltip(\"BullSh\")") assert(mcReverseType.refEntity(0)._1 == LinkToTpl(MyCollection), mcReverse.qualifiedName + "'s return type has a link to " + MyCollection.qualifiedName) } diff --git a/test/scaladoc/run/links.check b/test/scaladoc/run/links.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/links.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/links.scala b/test/scaladoc/run/links.scala new file mode 100644 index 0000000000..40ce6368ce --- /dev/null +++ b/test/scaladoc/run/links.scala @@ -0,0 +1,28 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +// SI-5079 "Scaladoc can't link to an object (only a class or trait)" +// SI-4497 "Links in ScalaDoc - Spec and implementation unsufficient" +// SI-4224 "Wiki-links should support method targets" +// SI-3695 "support non-fully-qualified type links in scaladoc comments" +object Test extends ScaladocModelTest { + + override def resourceFile = "links.scala" + + // no need for special settings + def scaladocSettings = "" + + 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")._package("links") + val TEST = base._object("TEST") + + val memberLinks = countLinks(TEST.comment.get, _.link.isInstanceOf[LinkToMember]) + val templateLinks = countLinks(TEST.comment.get, _.link.isInstanceOf[LinkToTpl]) + assert(memberLinks == 14, memberLinks + " == 14 (the member links in object TEST)") + assert(templateLinks == 2, templateLinks + " == 2 (the template links in object TEST)") + } +} \ No newline at end of file diff --git a/test/scaladoc/scalacheck/CommentFactoryTest.scala b/test/scaladoc/scalacheck/CommentFactoryTest.scala index b7869d5bf4..5e3141bdc0 100644 --- a/test/scaladoc/scalacheck/CommentFactoryTest.scala +++ b/test/scaladoc/scalacheck/CommentFactoryTest.scala @@ -10,7 +10,13 @@ import scala.tools.nsc.doc.model.diagram._ class Factory(val g: Global, val s: doc.Settings) extends doc.model.ModelFactory(g, s) { - thisFactory: Factory with ModelFactoryImplicitSupport with ModelFactoryTypeSupport with DiagramFactory with CommentFactory with doc.model.TreeFactory => + thisFactory: Factory + with ModelFactoryImplicitSupport + with ModelFactoryTypeSupport + with DiagramFactory + with CommentFactory + with doc.model.TreeFactory + with MemberLookup => def strip(c: Comment): Option[Inline] = { c.body match { @@ -31,7 +37,13 @@ object Test extends Properties("CommentFactory") { val settings = new doc.Settings((str: String) => {}) val reporter = new scala.tools.nsc.reporters.ConsoleReporter(settings) val g = new Global(settings, reporter) - (new Factory(g, settings) with ModelFactoryImplicitSupport with ModelFactoryTypeSupport with DiagramFactory with CommentFactory with doc.model.TreeFactory) + (new Factory(g, settings) + with ModelFactoryImplicitSupport + with ModelFactoryTypeSupport + with DiagramFactory + with CommentFactory + with doc.model.TreeFactory + with MemberLookup) } def parse(src: String, dst: Inline) = { -- cgit v1.2.3 From 740361b8ae5e9ac8c545b0be878bcae06070dcf0 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Tue, 10 Jul 2012 21:25:45 +0200 Subject: Scaladoc: Reducing the memory footprint - diagrams are not stored because they create many TypeEntities, nodes and edges -- now they are created on demand, so make sure you don't demand them twice! - eliminated the type entity cache, which was nearly useless (6s gain) but was preventing the GC from eliminating TypeEntities - an unsuccessful attempt at reducing the tons of :: garbage we're generating - there's 200MB-250MB of ::s during a typical 'ant docs.lib' --- src/compiler/scala/tools/nsc/doc/DocFactory.scala | 1 - .../scala/tools/nsc/doc/html/page/Template.scala | 26 ++++++++++--------- .../scala/tools/nsc/doc/model/ModelFactory.scala | 6 ++--- .../nsc/doc/model/ModelFactoryTypeSupport.scala | 30 +++++++++------------- .../nsc/doc/model/diagram/DiagramFactory.scala | 5 ++-- 5 files changed, 31 insertions(+), 37 deletions(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/DocFactory.scala b/src/compiler/scala/tools/nsc/doc/DocFactory.scala index 9fccc57e44..27a03d5381 100644 --- a/src/compiler/scala/tools/nsc/doc/DocFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/DocFactory.scala @@ -101,7 +101,6 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor println("no documentable class found in compilation units") None } - } object NoCompilerRunException extends ControlThrowable { } 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 cfd50db99f..417bfcfb96 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -601,13 +601,13 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp } val typeHierarchy = if (s.docDiagrams.isSetByUser) mbr match { - case dtpl: DocTemplateEntity if isSelf && !isReduced && dtpl.inheritanceDiagram.isDefined => + case dtpl: DocTemplateEntity if isSelf && !isReduced => makeDiagramHtml(dtpl, dtpl.inheritanceDiagram, "Type Hierarchy", "inheritance-diagram") case _ => NodeSeq.Empty } else NodeSeq.Empty // diagrams not generated val contentHierarchy = if (s.docDiagrams.isSetByUser) mbr match { - case dtpl: DocTemplateEntity if isSelf && !isReduced && dtpl.contentDiagram.isDefined => + case dtpl: DocTemplateEntity if isSelf && !isReduced => makeDiagramHtml(dtpl, dtpl.contentDiagram, "Content Hierarchy", "content-diagram") case _ => NodeSeq.Empty } else NodeSeq.Empty // diagrams not generated @@ -916,16 +916,18 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp } def makeDiagramHtml(tpl: DocTemplateEntity, diagram: Option[Diagram], description: String, id: String) = { - val s = universe.settings - val diagramSvg = generator.generate(diagram.get, tpl, this) - if (diagramSvg != NodeSeq.Empty) { -
    - { description } - Learn more about scaladoc diagrams -
    { - diagramSvg - }
    -
    + if (diagram.isDefined) { + val s = universe.settings + val diagramSvg = generator.generate(diagram.get, tpl, this) + if (diagramSvg != NodeSeq.Empty) { +
    + { description } + Learn more about scaladoc diagrams +
    { + diagramSvg + }
    +
    + } else NodeSeq.Empty } else NodeSeq.Empty } } diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 2642551aa8..d3d229d848 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -449,9 +449,9 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { case _ => None } - // We make the diagram a lazy val, since we're not sure we'll include the diagrams in the page - lazy val inheritanceDiagram = makeInheritanceDiagram(this) - lazy val contentDiagram = makeContentDiagram(this) + // These are generated on-demand, make sure you don't call them more than once + def inheritanceDiagram = makeInheritanceDiagram(this) + def contentDiagram = makeContentDiagram(this) } abstract class PackageImpl(sym: Symbol, inTpl: PackageImpl) extends DocTemplateImpl(sym, inTpl) with Package { diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala index 5efae3257c..d2a26d1309 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryTypeSupport.scala @@ -30,8 +30,7 @@ trait ModelFactoryTypeSupport { import definitions.{ ObjectClass, NothingClass, AnyClass, AnyValClass, AnyRefClass } import rootMirror.{ RootPackage, RootClass, EmptyPackage } - protected var typeCache = new mutable.LinkedHashMap[(Type, TemplateImpl), TypeEntity] - protected var typeCacheNoPrefix = new mutable.LinkedHashMap[Type, TypeEntity] + protected var typeCache = new mutable.LinkedHashMap[Type, TypeEntity] /** */ def makeType(aType: Type, inTpl: TemplateImpl): TypeEntity = { @@ -309,21 +308,16 @@ trait ModelFactoryTypeSupport { // SI-4360: Entity caching depends on both the type AND the template it's in, as the prefixes might change for the // same type based on the template the type is shown in. - val cached = - if (!settings.docNoPrefixes.value) - typeCache.get((aType, inTpl)) - else - typeCacheNoPrefix.get(aType) - - cached match { - case Some(typeEntity) => typeEntity - case None => - val typeEntity = createTypeEntity - if (!settings.docNoPrefixes.value) - typeCache += (aType, inTpl) -> typeEntity - else - typeCacheNoPrefix += aType -> typeEntity - typeEntity - } + if (settings.docNoPrefixes.value) { + val cached = typeCache.get(aType) + cached match { + case Some(typeEntity) => + typeEntity + case None => + val typeEntity = createTypeEntity + typeCache += aType -> typeEntity + typeEntity + } + } else createTypeEntity } } \ No newline at end of file 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 d0b363854c..9b56509623 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala @@ -61,9 +61,8 @@ trait DiagramFactory extends DiagramDirectiveParser { // subclasses var subclasses: List[Node] = - tpl.directSubClasses.flatMap { - case d: TemplateImpl if !classExcluded(d) => List(NormalNode(makeType(d.sym.tpe, tpl), Some(d))()) - case _ => Nil + tpl.directSubClasses.collect { + case d: TemplateImpl if !classExcluded(d) => NormalNode(makeType(d.sym.tpe, tpl), Some(d))() }.sortBy(_.tpl.get.name)(implicitly[Ordering[String]].reverse) // outgoing implicit coversions -- cgit v1.2.3 From b651269275a4cfd72761586e088bff5a130949b5 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Wed, 11 Jul 2012 22:28:00 +0200 Subject: Scaladoc: Reducing the memory footprint 2 - got rid of references to WikiParser when creating EntityLinks --- src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala | 3 +++ src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala b/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala index 7b131c13ef..277e86f9af 100644 --- a/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala +++ b/src/compiler/scala/tools/nsc/doc/model/MemberLookup.scala @@ -12,6 +12,9 @@ trait MemberLookup { import global._ + def makeEntityLink(title: Inline, pos: Position, query: String, inTplOpt: Option[DocTemplateImpl]) = + new EntityLink(title) { lazy val link = memberLookup(pos, query, inTplOpt) } + def memberLookup(pos: Position, query: String, inTplOpt: Option[DocTemplateImpl]): LinkTo = { assert(modelFinished) diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala index eff899b789..df913555a7 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala @@ -744,7 +744,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory with Member case (SchemeUri(uri), optTitle) => Link(uri, optTitle getOrElse Text(uri)) case (qualName, optTitle) => - new EntityLink(optTitle getOrElse Text(target)) { def link = memberLookup(pos, target, inTplOpt) } + makeEntityLink(optTitle getOrElse Text(target), pos, target, inTplOpt) } } -- cgit v1.2.3 From 0f2a0b7441153f3bdac49ca8878ffd9215458918 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Wed, 11 Jul 2012 23:56:32 +0200 Subject: Scaladoc: updated type class descriptions The known type class descriptions give you a humanly-understandable explanation for [T: TypeClass] in the implicit conversions. For example [T: Integral] will tell you that T must be an integral type such as Integer and co. Now that the reflection dust settled, I can actually add the test to make sure the well-known type classes are intercepted and explanations are given instead of the usual "the type T is context-bounded by TypeClass" --- src/compiler/scala/tools/ant/Scaladoc.scala | 1 - src/compiler/scala/tools/nsc/doc/Settings.scala | 19 +++++------ .../scala/tools/nsc/doc/model/Entity.scala | 3 ++ .../doc/model/ModelFactoryImplicitSupport.scala | 8 +++-- .../implicits-known-type-classes-res.scala | 38 ++++++++++++++++++++++ .../run/implicits-known-type-classes.check | 1 + .../run/implicits-known-type-classes.scala | 33 +++++++++++++++++++ 7 files changed, 90 insertions(+), 13 deletions(-) create mode 100644 test/scaladoc/resources/implicits-known-type-classes-res.scala create mode 100644 test/scaladoc/run/implicits-known-type-classes.check create mode 100644 test/scaladoc/run/implicits-known-type-classes.scala (limited to 'src') diff --git a/src/compiler/scala/tools/ant/Scaladoc.scala b/src/compiler/scala/tools/ant/Scaladoc.scala index 9aa2f6f921..61db3c7fa9 100644 --- a/src/compiler/scala/tools/ant/Scaladoc.scala +++ b/src/compiler/scala/tools/ant/Scaladoc.scala @@ -677,5 +677,4 @@ class Scaladoc extends ScalaMatchingTask { "(no error message provided); see the error output for details.") } } - } diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala index da478121e5..12b27387a7 100644 --- a/src/compiler/scala/tools/nsc/doc/Settings.scala +++ b/src/compiler/scala/tools/nsc/doc/Settings.scala @@ -209,16 +209,15 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) * the function result should be a humanly-understandable description of the type class */ val knownTypeClasses: Map[String, String => String] = Map() + - // TODO: Bring up to date and test these - ("scala.package.Numeric" -> ((tparam: String) => tparam + " is a numeric class, such as Int, Long, Float or Double")) + - ("scala.package.Integral" -> ((tparam: String) => tparam + " is an integral numeric class, such as Int or Long")) + - ("scala.package.Fractional" -> ((tparam: String) => tparam + " is a fractional numeric class, such as Float or Double")) + - ("scala.reflect.Manifest" -> ((tparam: String) => tparam + " is accompanied by a Manifest, which is a runtime representation of its type that survives erasure")) + - ("scala.reflect.ClassManifest" -> ((tparam: String) => tparam + " is accompanied by a ClassManifest, which is a runtime representation of its type that survives erasure")) + - ("scala.reflect.OptManifest" -> ((tparam: String) => tparam + " is accompanied by an OptManifest, which can be either a runtime representation of its type or the NoManifest, which means the runtime type is not available")) + - ("scala.reflect.ClassTag" -> ((tparam: String) => tparam + " is accompanied by a ClassTag, which is a runtime representation of its type that survives erasure")) + - ("scala.reflect.AbsTypeTag" -> ((tparam: String) => tparam + " is accompanied by an AbsTypeTag, which is a runtime representation of its type that survives erasure")) + - ("scala.reflect.TypeTag" -> ((tparam: String) => tparam + " is accompanied by a TypeTag, which is a runtime representation of its type that survives erasure")) + ("scala.math.Numeric" -> ((tparam: String) => tparam + " is a numeric class, such as Int, Long, Float or Double")) + + ("scala.math.Integral" -> ((tparam: String) => tparam + " is an integral numeric class, such as Int or Long")) + + ("scala.math.Fractional" -> ((tparam: String) => tparam + " is a fractional numeric class, such as Float or Double")) + + ("scala.reflect.Manifest" -> ((tparam: String) => tparam + " is accompanied by a Manifest, which is a runtime representation of its type that survives erasure")) + + ("scala.reflect.ClassManifest" -> ((tparam: String) => tparam + " is accompanied by a ClassManifest, which is a runtime representation of its type that survives erasure")) + + ("scala.reflect.OptManifest" -> ((tparam: String) => tparam + " is accompanied by an OptManifest, which can be either a runtime representation of its type or the NoManifest, which means the runtime type is not available")) + + ("scala.reflect.ClassTag" -> ((tparam: String) => tparam + " is accompanied by a ClassTag, which is a runtime representation of its type that survives erasure")) + + ("scala.reflect.AbsTypeTag" -> ((tparam: String) => tparam + " is accompanied by an AbsTypeTag, which is a runtime representation of its type that survives erasure")) + + ("scala.reflect.base.TypeTags.TypeTag" -> ((tparam: String) => tparam + " is accompanied by a TypeTag, which is a runtime representation of its type that survives erasure")) /** * Set of classes to exclude from index and diagrams diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index 42db408fee..626c1500f1 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -520,6 +520,9 @@ trait ImplicitConversion { /** The members inherited by this implicit conversion */ def members: List[MemberEntity] + + /** Is this a common implicit conversion (aka conversion that affects all classes, in Predef?) */ + def isCommonConversion: Boolean } /** Shadowing captures the information that the member is shadowed by some other members diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala index ddcdf1cf5c..bdae09e84d 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala @@ -115,7 +115,7 @@ trait ModelFactoryImplicitSupport { // Put the class-specific conversions in front val (ownConversions, commonConversions) = - conversions.partition(conv => !hardcoded.commonConversionTargets.contains(conv.conversionQualifiedName)) + conversions.partition(!_.isCommonConversion) ownConversions ::: commonConversions } @@ -347,7 +347,7 @@ trait ModelFactoryImplicitSupport { if (convSym != NoSymbol) makeTemplate(convSym.owner) else { - error("Scaladoc implicits: Implicit conversion from " + sym.tpe + " to " + toType + " done by " + convSym + " = NoSymbol!") + error("Scaladoc implicits: " + toString + " = NoSymbol!") makeRootPackage } @@ -415,6 +415,10 @@ trait ModelFactoryImplicitSupport { } lazy val members: List[MemberEntity] = memberImpls + + def isCommonConversion = hardcoded.commonConversionTargets.contains(conversionQualifiedName) + + override def toString = "Implcit conversion from " + sym.tpe + " to " + toType + " done by " + convSym } /* ========================= HELPER METHODS ========================== */ diff --git a/test/scaladoc/resources/implicits-known-type-classes-res.scala b/test/scaladoc/resources/implicits-known-type-classes-res.scala new file mode 100644 index 0000000000..9ad652947d --- /dev/null +++ b/test/scaladoc/resources/implicits-known-type-classes-res.scala @@ -0,0 +1,38 @@ +/** Tests the "known type classes" feature of scaladoc implicits + * if the test fails, please update the correct qualified name of + * the type class in src/compiler/scala/tools/nsc/doc/Settings.scala + * in the knownTypeClasses map. Thank you! */ +package scala.test.scaladoc.implicits.typeclasses { + class A[T] + object A { + import language.implicitConversions + import scala.reflect.{ClassTag, TypeTag} + implicit def convertNumeric [T: Numeric] (a: A[T]) = new B(implicitly[Numeric[T]]) + implicit def convertIntegral [T: Integral] (a: A[T]) = new B(implicitly[Integral[T]]) + implicit def convertFractional [T: Fractional] (a: A[T]) = new B(implicitly[Fractional[T]]) + implicit def convertManifest [T: Manifest] (a: A[T]) = new B(implicitly[Manifest[T]]) + implicit def convertClassManifest [T: ClassManifest] (a: A[T]) = new B(implicitly[ClassManifest[T]]) + implicit def convertOptManifest [T: OptManifest] (a: A[T]) = new B(implicitly[OptManifest[T]]) + implicit def convertClassTag [T: ClassTag] (a: A[T]) = new B(implicitly[ClassTag[T]]) + implicit def convertTypeTag [T: TypeTag] (a: A[T]) = new B(implicitly[TypeTag[T]]) + type K[X] = Numeric[X] + type L[X] = Integral[X] + type M[X] = Fractional[X] + type N[X] = Manifest[X] + type O[X] = ClassManifest[X] + type P[X] = OptManifest[X] + type Q[X] = ClassTag[X] + type R[X] = TypeTag[X] + implicit def convertK [T: K] (a: A[T]) = new B(implicitly[K[T]]) + implicit def convertL [T: L] (a: A[T]) = new B(implicitly[L[T]]) + implicit def convertM [T: M] (a: A[T]) = new B(implicitly[M[T]]) + implicit def convertN [T: N] (a: A[T]) = new B(implicitly[N[T]]) + implicit def convertO [T: O] (a: A[T]) = new B(implicitly[O[T]]) + implicit def convertP [T: P] (a: A[T]) = new B(implicitly[P[T]]) + implicit def convertQ [T: Q] (a: A[T]) = new B(implicitly[Q[T]]) + implicit def convertR [T: R] (a: A[T]) = new B(implicitly[R[T]]) + } + class B[T](t: T) { + def typeClass: T = t + } +} \ No newline at end of file diff --git a/test/scaladoc/run/implicits-known-type-classes.check b/test/scaladoc/run/implicits-known-type-classes.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/implicits-known-type-classes.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/implicits-known-type-classes.scala b/test/scaladoc/run/implicits-known-type-classes.scala new file mode 100644 index 0000000000..9f4ca372b0 --- /dev/null +++ b/test/scaladoc/run/implicits-known-type-classes.scala @@ -0,0 +1,33 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest +import language._ + +object Test extends ScaladocModelTest { + + // test a file instead of a piece of code + override def resourceFile = "implicits-known-type-classes-res.scala" + + // start implicits + def scaladocSettings = "-implicits" + + def testModel(root: Package) = { + // get the quick access implicit defs in scope (_package(s), _class(es), _trait(s), object(s) _method(s), _value(s)) + import access._ + + /** Tests the "known type classes" feature of scaladoc implicits + * if the test fails, please update the correct qualified name of + * the type class in src/compiler/scala/tools/nsc/doc/Settings.scala + * in the knownTypeClasses map. Thank you! */ + + val base = root._package("scala")._package("test")._package("scaladoc")._package("implicits")._package("typeclasses") + var conv: ImplicitConversion = null + + val A = base._class("A") + + for (conversion <- A.conversions if !conversion.isCommonConversion) { + assert(conversion.constraints.length == 1, conversion.constraints.length + " == 1 (in " + conversion + ")") + assert(conversion.constraints.head.isInstanceOf[KnownTypeClassConstraint], + conversion.constraints.head + " is not a known type class constraint!") + } + } +} -- cgit v1.2.3 From 376403266c699190882ef7c9f2a7c65c86a23a3d Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Fri, 13 Jul 2012 15:59:01 +0200 Subject: SI-5533 Skip scaladoc packages from documentation --- src/compiler/scala/tools/nsc/doc/Settings.scala | 18 ++++++- .../scala/tools/nsc/doc/model/Entity.scala | 3 ++ .../scala/tools/nsc/doc/model/ModelFactory.scala | 59 +++++++++++----------- .../nsc/doc/model/diagram/DiagramFactory.scala | 2 +- .../scala/tools/partest/ScaladocModelTest.scala | 11 +++- test/scaladoc/run/SI-3314-diagrams.scala | 9 ---- test/scaladoc/run/SI-5533.check | 1 + test/scaladoc/run/SI-5533.scala | 37 ++++++++++++++ 8 files changed, 98 insertions(+), 42 deletions(-) create mode 100644 test/scaladoc/run/SI-5533.check create mode 100644 test/scaladoc/run/SI-5533.scala (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala index 12b27387a7..7cb539feee 100644 --- a/src/compiler/scala/tools/nsc/doc/Settings.scala +++ b/src/compiler/scala/tools/nsc/doc/Settings.scala @@ -176,6 +176,13 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) "Avoid warnings for ambiguous and incorrect links." ) + val docSkipPackages = StringSetting ( + "-skip-packages", + ":...:", + "A colon-delimited list of fully qualified package names that will be skipped from scaladoc.", + "" + ) + // Somewhere slightly before r18708 scaladoc stopped building unless the // self-type check was suppressed. I hijacked the slotted-for-removal-anyway // suppress-vt-warnings option and renamed it for this purpose. @@ -188,7 +195,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) docDiagramsDotTimeout, docDiagramsDotRestart, docImplicits, docImplicitsDebug, docImplicitsShowAll, docDiagramsMaxNormalClasses, docDiagramsMaxImplicitClasses, - docNoPrefixes, docNoLinkWarnings, docRawOutput + docNoPrefixes, docNoLinkWarnings, docRawOutput, docSkipPackages ) val isScaladocSpecific: String => Boolean = scaladocSpecific map (_.name) @@ -197,6 +204,15 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) // set by the testsuite, when checking test output var scaladocQuietRun = false + lazy val skipPackageNames = + if (docSkipPackages.value == "") + Set[String]() + else + docSkipPackages.value.toLowerCase.split(':').toSet + + def skipPackage(qname: String) = + skipPackageNames(qname.toLowerCase) + /** * This is the hardcoded area of Scaladoc. This is where "undesirable" stuff gets eliminated. I know it's not pretty, * but ultimately scaladoc has to be useful. :) diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index 626c1500f1..d9758c6f2f 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -97,6 +97,9 @@ trait TemplateEntity extends Entity { /** Whether documentation is available for this template. */ def isDocTemplate: Boolean + /** Whether documentation is available for this template. */ + def isNoDocMemberTemplate: Boolean + /** Whether this template is a case class. */ def isCaseClass: Boolean diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index d3d229d848..2fec832db8 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -106,6 +106,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def isObject = sym.isModule && !sym.isPackage def isCaseClass = sym.isCaseClass def isRootPackage = false + def isNoDocMemberTemplate = false def selfType = if (sym.thisSym eq sym) None else Some(makeType(sym.thisSym.typeOfThis, this)) } @@ -270,6 +271,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { // no templates cache for this class, each owner gets its own instance override def isTemplate = true def isDocTemplate = false + override def isNoDocMemberTemplate = true lazy val definitionName = optimize(inDefinitionTemplates.head.qualifiedName + "." + name) } @@ -518,7 +520,29 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { } /* ============== MAKER METHODS ============== */ - /** */ + /** This method makes it easier to work with the different kinds of symbols created by scalac + * + * Okay, here's the explanation of what happens. The code: + * + * package foo { + * object `package` { + * class Bar + * } + * } + * + * will yield this Symbol structure: + * + * +---------------+ +--------------------------+ + * | package foo#1 ----(1)---> module class foo#2 | + * +---------------+ | +----------------------+ | +-------------------------+ + * | | package object foo#3 ------(1)---> module class package#4 | + * | +----------------------+ | | +---------------------+ | + * +--------------------------+ | | class package$Bar#5 | | + * | +---------------------+ | + * +-------------------------+ + * (1) sourceModule + * (2) you get out of owners with .owner + */ def normalizeTemplate(aSym: Symbol): Symbol = aSym match { case null | rootMirror.EmptyPackage | NoSymbol => normalizeTemplate(RootPackage) @@ -528,8 +552,6 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { normalizeTemplate(aSym.owner) case _ if aSym.isModuleClass => normalizeTemplate(aSym.sourceModule) - // case t: ThisType => - // t. case _ => aSym } @@ -720,6 +742,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { override def useCaseOf = _useCaseOf }) else if (bSym.isPackage && !modelFinished) + if (settings.skipPackage(makeQualifiedName(bSym))) None else inTpl match { case inPkg: PackageImpl => modelCreation.createTemplate(bSym, inTpl) match { case p: PackageImpl if droppedPackages contains p => None @@ -933,33 +956,8 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { //path.mkString(".") } - def normalizeOwner(aSym: Symbol): Symbol = - /* - * Okay, here's the explanation of what happens. The code: - * - * package foo { - * object `package` { - * class Bar - * } - * } - * - * will yield this Symbol structure: - * - * +---------------+ +--------------------------+ - * | package foo#1 ----(1)---> module class foo#2 | - * +---------------+ | +----------------------+ | +-------------------------+ - * | | package object foo#3 ------(1)---> module class package#4 | - * | +----------------------+ | | +---------------------+ | - * +--------------------------+ | | class package$Bar#5 | | - * | +---------------------+ | - * +-------------------------+ - * (1) sourceModule - * (2) you get out of owners with .owner - */ - normalizeTemplate(aSym) - def inOriginalOwner(aSym: Symbol, inTpl: TemplateImpl): Boolean = - normalizeOwner(aSym.owner) == normalizeOwner(inTpl.sym) + normalizeTemplate(aSym.owner) == normalizeTemplate(inTpl.sym) def templateShouldDocument(aSym: Symbol, inTpl: TemplateImpl): Boolean = (aSym.isClass || aSym.isModule || aSym == AnyRefClass) && @@ -968,7 +966,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { // either it's inside the original owner or we can document it later: (!inOriginalOwner(aSym, inTpl) || (aSym.isPackageClass || (aSym.sourceFile != null))) - def membersShouldDocument(sym: Symbol, inTpl: TemplateImpl) = + def membersShouldDocument(sym: Symbol, inTpl: TemplateImpl) = { // pruning modules that shouldn't be documented // Why Symbol.isInitialized? Well, because we need to avoid exploring all the space available to scaladoc // from the classpath -- scaladoc is a hog, it will explore everything starting from the root package unless we @@ -981,6 +979,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { (!sym.isConstructor || sym.owner == inTpl.sym) && // If the @bridge annotation overrides a normal member, show it !isPureBridge(sym) + } def isEmptyJavaObject(aSym: Symbol): Boolean = aSym.isModule && aSym.isJavaDefined && 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 9b56509623..e0f6d42a68 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala @@ -142,7 +142,7 @@ trait DiagramFactory extends DiagramDirectiveParser { } mapNodes += node -> ( - if (node.inTemplate == pack) + if (node.inTemplate == pack && !node.isNoDocMemberTemplate) NormalNode(node.resultType, Some(node))() else OutsideNode(node.resultType, Some(node))() diff --git a/src/partest/scala/tools/partest/ScaladocModelTest.scala b/src/partest/scala/tools/partest/ScaladocModelTest.scala index fb93e98726..fc540f83fe 100644 --- a/src/partest/scala/tools/partest/ScaladocModelTest.scala +++ b/src/partest/scala/tools/partest/ScaladocModelTest.scala @@ -11,8 +11,9 @@ import scala.tools.nsc._ import scala.tools.nsc.util.CommandLineParser import scala.tools.nsc.doc.{Settings, DocFactory, Universe} import scala.tools.nsc.doc.model._ -import scala.tools.nsc.reporters.ConsoleReporter +import scala.tools.nsc.doc.model.diagram._ import scala.tools.nsc.doc.model.comment._ +import scala.tools.nsc.reporters.ConsoleReporter /** A class for testing scaladoc model generation * - you need to specify the code in the `code` method @@ -181,5 +182,13 @@ abstract class ScaladocModelTest extends DirectTest { } countLinks(c.body) } + + 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.map(_._2.length).sum == edges, + doc.qualifiedName + "'s diagram: edge count " + diag.get.edges.length + " == " + edges) + } } } diff --git a/test/scaladoc/run/SI-3314-diagrams.scala b/test/scaladoc/run/SI-3314-diagrams.scala index 0b07e4c5bd..050c6e7f48 100644 --- a/test/scaladoc/run/SI-3314-diagrams.scala +++ b/test/scaladoc/run/SI-3314-diagrams.scala @@ -1,5 +1,4 @@ import scala.tools.nsc.doc.model._ -import scala.tools.nsc.doc.model.diagram._ import scala.tools.partest.ScaladocModelTest object Test extends ScaladocModelTest { @@ -17,14 +16,6 @@ object Test extends ScaladocModelTest { 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) { diff --git a/test/scaladoc/run/SI-5533.check b/test/scaladoc/run/SI-5533.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-5533.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-5533.scala b/test/scaladoc/run/SI-5533.scala new file mode 100644 index 0000000000..e7b5f57860 --- /dev/null +++ b/test/scaladoc/run/SI-5533.scala @@ -0,0 +1,37 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + // Working around the fact that usecases have the form Coll[T] and not Coll[T, U], as required by Map + override def code = """ + package a { + class A { class Z } + class C extends b.B { class X extends Y } + } + + package b { + /** @contentDiagram */ + class B extends a.A { class Y extends Z } + /** @contentDiagram */ + class D extends a.C { class V extends X } + } + """ + + // no need for special settings + def scaladocSettings = "-diagrams -skip-packages a" + + 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 + assert(!rootPackage.templates.exists(_.name == "a"), "package a should not exist in the root package") + assert(rootPackage.templates.exists(_.name == "b"), "package b should exist in the root package") + val b = rootPackage._package("b") + val B = b._class("B") + val D = b._class("D") + testDiagram(B, B.contentDiagram, 2, 1) + testDiagram(D, D.contentDiagram, 2, 1) + } +} \ No newline at end of file -- cgit v1.2.3 From 17f745d33cbda90aa552c95bc5456ed793180333 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Mon, 16 Jul 2012 13:32:05 +0200 Subject: Scaladoc: Refactoring the entities for SI-5784. This commit has been checked with tools/scaladoc-compare and the only difference is that the containing entities in the index are not duplicate anymore, which solves yet another bug we did not know about. :) --- src/compiler/scala/tools/nsc/doc/html/Page.scala | 22 ++- .../scala/tools/nsc/doc/html/page/Index.scala | 2 +- .../tools/nsc/doc/html/page/IndexScript.scala | 2 +- .../scala/tools/nsc/doc/html/page/Template.scala | 16 +- .../scala/tools/nsc/doc/model/Entity.scala | 55 +++---- .../tools/nsc/doc/model/IndexModelFactory.scala | 7 +- .../scala/tools/nsc/doc/model/ModelFactory.scala | 172 ++++++++++++--------- .../doc/model/ModelFactoryImplicitSupport.scala | 2 +- .../scala/tools/partest/ScaladocModelTest.scala | 12 +- test/scaladoc/run/diagrams-determinism.scala | 20 +-- test/scaladoc/run/diagrams-filtering.scala | 2 +- test/scaladoc/run/implicits-ambiguating.scala | 2 +- test/scaladoc/run/implicits-shadowing.scala | 2 +- 13 files changed, 159 insertions(+), 157 deletions(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/html/Page.scala b/src/compiler/scala/tools/nsc/doc/html/Page.scala index 08df26e745..d30ca5dc08 100644 --- a/src/compiler/scala/tools/nsc/doc/html/Page.scala +++ b/src/compiler/scala/tools/nsc/doc/html/Page.scala @@ -48,13 +48,21 @@ abstract class Page { * @param generator The generator that is writing this page. */ def writeFor(site: HtmlFactory): Unit - def docEntityKindToString(ety: TemplateEntity) = - if (ety.isTrait) "trait" - else if (ety.isCaseClass) "case class" - else if (ety.isClass) "class" - else if (ety.isObject) "object" - else if (ety.isPackage) "package" - else "class" // FIXME: an entity *should* fall into one of the above categories, but AnyRef is somehow not + def kindToString(mbr: MemberEntity) = + mbr match { + case c: Class => if (c.isCaseClass) "case class" else "class" + case _: Trait => "trait" + case _: Package => "package" + case _: Object => "object" + case _: AbstractType => "type" + case _: AliasType => "type" + case _: Constructor => "new" + case v: Def => "def" + case v: Val if (v.isLazyVal) => "lazy val" + case v: Val if (v.isVal) => "val" + case v: Val if (v.isVar) => "var" + case _ => sys.error("Cannot create kind for: " + mbr + " of class " + mbr.getClass) + } def templateToPath(tpl: TemplateEntity): List[String] = { def doName(tpl: TemplateEntity): String = diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala index 81fbed884d..b15d602b57 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala @@ -68,7 +68,7 @@ class Index(universe: doc.Universe, val index: doc.Index) extends HtmlPage { val placeholderSeq: NodeSeq =
    def createLink(entity: DocTemplateEntity, includePlaceholder: Boolean, includeText: Boolean) = { - val entityType = docEntityKindToString(entity) + val entityType = kindToString(entity) val linkContent = ( { if (includePlaceholder) placeholderSeq else NodeSeq.Empty } ++ diff --git a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala index e1ab479f9d..a37dd3fb8b 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala @@ -27,7 +27,7 @@ class IndexScript(universe: doc.Universe, index: doc.Index) extends Page { val ary = merged.keys.toList.sortBy(_.toLowerCase).map(key => { val pairs = merged(key).map( - t => docEntityKindToString(t) -> relativeLinkTo(t) + t => kindToString(t) -> relativeLinkTo(t) ) :+ ("name" -> key) JSONObject(scala.collection.immutable.Map(pairs : _*)) 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 417bfcfb96..d691692920 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -67,7 +67,7 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp nonDeprValueMembers partition (!_.isShadowedOrAmbiguousImplicit) val typeMembers = - tpl.abstractTypes ++ tpl.aliasTypes ++ tpl.templates.filter(x => x.isTrait || x.isClass) sorted + tpl.abstractTypes ++ tpl.aliasTypes ++ tpl.templates.filter(x => x.isTrait || x.isClass) sorted (implicitly[Ordering[MemberEntity]]) val constructors = (tpl match { case cls: Class => (cls.constructors: List[MemberEntity]).sorted @@ -615,20 +615,6 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp memberComment ++ paramComments ++ attributesBlock ++ linearization ++ subclasses ++ typeHierarchy ++ contentHierarchy } - def kindToString(mbr: MemberEntity): String = { - mbr match { - case tpl: DocTemplateEntity => docEntityKindToString(tpl) - case tpl: NoDocTemplateMemberEntity => docEntityKindToString(tpl) - case ctor: Constructor => "new" - case tme: MemberEntity => - ( if (tme.isDef) "def" - else if (tme.isVal) "val" - else if (tme.isLazyVal) "lazy val" - else if (tme.isVar) "var" - else "type") - } - } - def boundsToHtml(hi: Option[TypeEntity], lo: Option[TypeEntity], hasLinks: Boolean): NodeSeq = { def bound0(bnd: Option[TypeEntity], pre: String): NodeSeq = bnd match { case None => NodeSeq.Empty diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index d9758c6f2f..620aa4253f 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -185,7 +185,7 @@ trait MemberEntity extends Entity { /** If this symbol is a use case, the useCaseOf will contain the member it was derived from, containing the full * signature and the complete parameter descriptions. */ - def useCaseOf: Option[MemberEntity] = None + def useCaseOf: Option[MemberEntity] /** If this member originates from an implicit conversion, we set the implicit information to the correct origin */ def byConversion: Option[ImplicitConversion] @@ -225,22 +225,27 @@ trait HigherKinded { /** 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 { - def kind = "" - //def kind = "(not documented) template" + def kind = + if (isClass) "class" + else if (isTrait) "trait" + else if (isObject) "object" + else "" } /** An inherited template that was not documented in its original owner - example: * in classpath: trait T { class C } -- T (and implicitly C) are not documented - * in the source: trait U extends T -- C appears in U as a NoDocTemplateMemberImpl + * in the source: trait U extends T -- C appears in U as a MemberTemplateImpl * -- that is, U has a member for it but C doesn't get its own page */ -trait NoDocTemplateMemberEntity extends TemplateEntity with MemberEntity { - def kind = "" - //def kind = "(not documented) member template" +trait MemberTemplateEntity extends TemplateEntity with MemberEntity with HigherKinded { + + /** The value parameters of this case class, or an empty list if this class is not a case class. As case class value + * parameters cannot be curried, the outer list has exactly one element. */ + def valueParams: List[List[ValueParam]] } /** 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 { +trait DocTemplateEntity extends MemberTemplateEntity { /** 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. */ @@ -295,6 +300,12 @@ trait DocTemplateEntity extends TemplateEntity with MemberEntity { /** All type aliases that are members of this template. */ def aliasTypes: List[AliasType] + /** 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 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] @@ -319,39 +330,24 @@ trait DocTemplateEntity extends TemplateEntity with MemberEntity { def contentDiagram: Option[Diagram] } - /** A trait template. */ -trait Trait extends DocTemplateEntity with HigherKinded { +trait Trait extends MemberTemplateEntity { def kind = "trait" } - /** 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 - * parameters cannot be curried, the outer list has exactly one element. */ - def valueParams: List[List[ValueParam]] - +trait Class extends MemberTemplateEntity { override def kind = "class" } - /** An object template. */ -trait Object extends DocTemplateEntity { +trait Object extends MemberTemplateEntity { def kind = "object" } - /** 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 { +trait Package extends DocTemplateEntity { /** The package of which this package is a member. */ def inTemplate: Package @@ -382,7 +378,6 @@ trait NonTemplateMemberEntity extends MemberEntity { /** Whether this member is a bridge member. A bridge member does only exist for binary compatibility reasons * and should not appear in ScalaDoc. */ def isBridge: Boolean - } @@ -419,7 +414,7 @@ trait Val extends NonTemplateMemberEntity { /** An abstract type member of a template. */ -trait AbstractType extends NonTemplateMemberEntity with HigherKinded { +trait AbstractType extends MemberTemplateEntity with HigherKinded { /** The lower bound for this abstract type, if it has been defined. */ def lo: Option[TypeEntity] @@ -432,7 +427,7 @@ trait AbstractType extends NonTemplateMemberEntity with HigherKinded { /** An type alias of a template. */ -trait AliasType extends NonTemplateMemberEntity with HigherKinded { +trait AliasType extends MemberTemplateEntity with HigherKinded { /** The type aliased by this type alias. */ def alias: TypeEntity diff --git a/src/compiler/scala/tools/nsc/doc/model/IndexModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/IndexModelFactory.scala index 6392de22ff..f4c96505a7 100755 --- a/src/compiler/scala/tools/nsc/doc/model/IndexModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/IndexModelFactory.scala @@ -36,7 +36,6 @@ object IndexModelFactory { } + d this(firstLetter) = letter + (d.name -> members) } - } //@scala.annotation.tailrec // TODO @@ -46,11 +45,7 @@ object IndexModelFactory { case tpl: DocTemplateEntity => result.addMember(tpl) gather(tpl) - case alias: AliasType => - result.addMember(alias) - case absType: AbstractType => - result.addMember(absType) - case non: NonTemplateMemberEntity if !non.isConstructor => + case non: MemberEntity if !non.isConstructor => result.addMember(non) case x @ _ => } diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 2fec832db8..fc5fde3239 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -110,26 +110,16 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def selfType = if (sym.thisSym eq sym) None else Some(makeType(sym.thisSym.typeOfThis, this)) } - abstract class MemberImpl(sym: Symbol, implConv: ImplicitConversionImpl, inTpl: DocTemplateImpl) extends EntityImpl(sym, inTpl) with MemberEntity { + abstract class MemberImpl(sym: Symbol, inTpl: DocTemplateImpl) extends EntityImpl(sym, inTpl) with MemberEntity { lazy val comment = { - val inRealTpl = - /* Variable precendence order for implicitly added members: Take the variable defifinitions from ... - * 1. the target of the implicit conversion - * 2. the definition template (owner) - * 3. the current template - */ - if (implConv != null) findTemplateMaybe(implConv.toType.typeSymbol) match { - case Some(d) if d != makeRootPackage => d //in case of NoSymbol, it will give us the root package - case _ => findTemplateMaybe(sym.owner) match { - case Some(d) if d != makeRootPackage => d //in case of NoSymbol, it will give us the root package - case _ => inTpl - } - } else inTpl + // If the current tpl is a DocTemplate, we consider itself as the root for resolving link targets (instead of the + // package the class is in) -- so people can refer to methods directly [[foo]], instead of using [[MyClass.foo]] + // in the doc comment of MyClass val thisTpl = this match { case d: DocTemplateImpl => Some(d) case _ => None } - if (inRealTpl != null) thisFactory.comment(sym, thisTpl, inRealTpl) else None + if (inTpl != null) thisFactory.comment(sym, thisTpl, inTpl) else None } override def inTemplate = inTpl override def toRoot: List[MemberImpl] = this :: inTpl.toRoot @@ -168,7 +158,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { * }}} * the type the method returns is TraversableOps, which has all-abstract symbols. But in reality, it couldn't have * any abstract terms, otherwise it would fail compilation. So we reset the DEFERRED flag. */ - if (!sym.isTrait && (sym hasFlag Flags.DEFERRED) && (implConv eq null)) fgs += Paragraph(Text("abstract")) + if (!sym.isTrait && (sym hasFlag Flags.DEFERRED) && (!isImplicitlyInherited)) fgs += Paragraph(Text("abstract")) if (!sym.isModule && (sym hasFlag Flags.FINAL)) fgs += Paragraph(Text("final")) fgs.toList } @@ -202,7 +192,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { case NullaryMethodType(res) => resultTpe(res) case _ => tpe } - val tpe = if (implConv eq null) sym.tpe else implConv.toType memberInfo sym + val tpe = if (!isImplicitlyInherited) sym.tpe else byConversion.get.toType memberInfo sym makeTypeInTemplateContext(resultTpe(tpe), inTemplate, sym) } def isDef = false @@ -214,11 +204,10 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def isAliasType = false def isAbstractType = false def isAbstract = - // for the explanation of implConv == null see comment on flags - ((!sym.isTrait && ((sym hasFlag Flags.ABSTRACT) || (sym hasFlag Flags.DEFERRED)) && (implConv == null)) || + // for the explanation of conversion == null see comment on flags + ((!sym.isTrait && ((sym hasFlag Flags.ABSTRACT) || (sym hasFlag Flags.DEFERRED)) && (!isImplicitlyInherited)) || sym.isAbstractClass || sym.isAbstractType) && !sym.isSynthetic def isTemplate = false - def byConversion = if (implConv ne null) Some(implConv) else None lazy val signature = { def defParams(mbr: Any): String = mbr match { @@ -245,10 +234,13 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { (name + tParams(this) + defParams(this) +":"+ resultType.name).replaceAll("\\s","") // no spaces allowed, they break links } - def isImplicitlyInherited = { assert(modelFinished); byConversion.isDefined } - def isShadowedImplicit = isImplicitlyInherited && inTpl.implicitsShadowing.get(this).map(_.isShadowed).getOrElse(false) - def isAmbiguousImplicit = isImplicitlyInherited && inTpl.implicitsShadowing.get(this).map(_.isAmbiguous).getOrElse(false) - def isShadowedOrAmbiguousImplicit = isShadowedImplicit || isAmbiguousImplicit + // these only apply for NonTemplateMemberEntities + def useCaseOf: Option[MemberEntity] = None + def byConversion: Option[ImplicitConversionImpl] = None + def isImplicitlyInherited = false + def isShadowedImplicit = false + def isAmbiguousImplicit = false + def isShadowedOrAmbiguousImplicit = false } /** A template that is not documented at all. The class is instantiated during lookups, to indicate that the class @@ -263,22 +255,22 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { /** An inherited template that was not documented in its original owner - example: * in classpath: trait T { class C } -- T (and implicitly C) are not documented - * in the source: trait U extends T -- C appears in U as a NoDocTemplateMemberImpl -- that is, U has a member for it + * in the source: trait U extends T -- C appears in U as a MemberTemplateImpl -- that is, U has a member for it * but C doesn't get its own page */ - class NoDocTemplateMemberImpl(sym: Symbol, inTpl: DocTemplateImpl) extends MemberImpl(sym, null, inTpl) with TemplateImpl with HigherKindedImpl with NoDocTemplateMemberEntity { - assert(modelFinished) + abstract class MemberTemplateImpl(sym: Symbol, inTpl: DocTemplateImpl) extends MemberImpl(sym, inTpl) with TemplateImpl with HigherKindedImpl with MemberTemplateEntity { // no templates cache for this class, each owner gets its own instance override def isTemplate = true def isDocTemplate = false override def isNoDocMemberTemplate = true lazy val definitionName = optimize(inDefinitionTemplates.head.qualifiedName + "." + name) + def valueParams: List[List[ValueParam]] = Nil /** TODO, these are now only computed for DocTemplates */ } /** The instantiation of `TemplateImpl` triggers the creation of the following entities: * All ancestors of the template and all non-package members. */ - abstract class DocTemplateImpl(sym: Symbol, inTpl: DocTemplateImpl) extends MemberImpl(sym, null, inTpl) with TemplateImpl with HigherKindedImpl with DocTemplateEntity { + abstract class DocTemplateImpl(sym: Symbol, inTpl: DocTemplateImpl) extends MemberTemplateImpl(sym, inTpl) with DocTemplateEntity { assert(!modelFinished) assert(!(docTemplatesCache isDefinedAt sym), sym) docTemplatesCache += (sym -> this) @@ -386,7 +378,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { // the direct members (methods, values, vars, types and directly contained templates) var memberSymsEager = memberSyms.filter(!memberSymsLazy.contains(_)) // the members generated by the symbols in memberSymsEager - val ownMembers = (memberSyms.flatMap(makeMember(_, null, this))) + val ownMembers = (memberSyms.flatMap(makeMember(_, None, this))) // all the members that are documentented PLUS the members inherited by implicit conversions var members: List[MemberImpl] = ownMembers @@ -439,8 +431,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { ) override def isTemplate = true - lazy val definitionName = optimize(inDefinitionTemplates.head.qualifiedName + "." + name) - def isDocTemplate = true + override def isDocTemplate = true def companion = sym.companionSymbol match { case NoSymbol => None case comSym if !isEmptyJavaObject(comSym) && (comSym.isClass || comSym.isModule) => @@ -451,6 +442,15 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { case _ => None } + def constructors: List[MemberImpl with Constructor] = if (isClass) members collect { case d: Constructor => d } else Nil + def primaryConstructor: Option[MemberImpl with Constructor] = if (isClass) constructors find { _.isPrimary } else None + override def valueParams = + // we don't want params on a class (non case class) signature + if (isCaseClass) primaryConstructor match { + case Some(const) => const.sym.paramss map (_ map (makeValueParam(_, this))) + case None => List() + } + else List.empty // These are generated on-demand, make sure you don't call them more than once def inheritanceDiagram = makeInheritanceDiagram(this) def contentDiagram = makeContentDiagram(this) @@ -470,23 +470,49 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { abstract class RootPackageImpl(sym: Symbol) extends PackageImpl(sym, null) with RootPackageEntity - abstract class NonTemplateMemberImpl(sym: Symbol, implConv: ImplicitConversionImpl, inTpl: DocTemplateImpl) extends MemberImpl(sym, implConv, inTpl) with NonTemplateMemberEntity { + abstract class NonTemplateMemberImpl(sym: Symbol, conversion: Option[ImplicitConversionImpl], + override val useCaseOf: Option[MemberEntity], inTpl: DocTemplateImpl) + extends MemberImpl(sym, inTpl) with NonTemplateMemberEntity { + override lazy val comment = { + val inRealTpl = + /* Variable precendence order for implicitly added members: Take the variable defifinitions from ... + * 1. the target of the implicit conversion + * 2. the definition template (owner) + * 3. the current template + */ + if (conversion.isDefined) findTemplateMaybe(conversion.get.toType.typeSymbol) match { + case Some(d) if d != makeRootPackage => d //in case of NoSymbol, it will give us the root package + case _ => findTemplateMaybe(sym.owner) match { + case Some(d) if d != makeRootPackage => d //in case of NoSymbol, it will give us the root package + case _ => inTpl + } + } else inTpl + if (inRealTpl != null) thisFactory.comment(sym, None, inRealTpl) else None + } + override def qualifiedName = optimize(inTemplate.qualifiedName + "#" + name) lazy val definitionName = { // this contrived name is here just to satisfy some older tests -- if you decide to remove it, be my guest, and // also remove property("package object") from test/scaladoc/scalacheck/HtmlFactoryTest.scala so you don't break // the test suite... val packageObject = if (inPackageObject) ".package" else "" - if (implConv == null) optimize(inDefinitionTemplates.head.qualifiedName + packageObject + "#" + name) - else optimize(implConv.conversionQualifiedName + packageObject + "#" + name) + if (!conversion.isDefined) optimize(inDefinitionTemplates.head.qualifiedName + packageObject + "#" + name) + else optimize(conversion.get.conversionQualifiedName + packageObject + "#" + name) } - def isUseCase = sym.isSynthetic def isBridge = sym.isBridge + def isUseCase = useCaseOf.isDefined + override def byConversion: Option[ImplicitConversionImpl] = conversion + override def isImplicitlyInherited = { assert(modelFinished); conversion.isDefined } + override def isShadowedImplicit = isImplicitlyInherited && inTpl.implicitsShadowing.get(this).map(_.isShadowed).getOrElse(false) + override def isAmbiguousImplicit = isImplicitlyInherited && inTpl.implicitsShadowing.get(this).map(_.isAmbiguous).getOrElse(false) + override def isShadowedOrAmbiguousImplicit = isShadowedImplicit || isAmbiguousImplicit } - abstract class NonTemplateParamMemberImpl(sym: Symbol, implConv: ImplicitConversionImpl, inTpl: DocTemplateImpl) extends NonTemplateMemberImpl(sym, implConv, inTpl) { + abstract class NonTemplateParamMemberImpl(sym: Symbol, conversion: Option[ImplicitConversionImpl], + useCaseOf: Option[MemberEntity], inTpl: DocTemplateImpl) + extends NonTemplateMemberImpl(sym, conversion, useCaseOf, inTpl) { def valueParams = { - val info = if (implConv eq null) sym.info else implConv.toType memberInfo sym + val info = if (!isImplicitlyInherited) sym.info else conversion.get.toType memberInfo sym info.paramss map { ps => (ps.zipWithIndex) map { case (p, i) => if (p.nameString contains "$") makeValueParam(p, inTpl, optimize("arg" + i)) else makeValueParam(p, inTpl) }} @@ -591,24 +617,13 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def createDocTemplate(bSym: Symbol, inTpl: DocTemplateImpl): DocTemplateImpl = { assert(!modelFinished) // only created BEFORE the model is finished if (bSym.isModule || (bSym.isAliasType && bSym.tpe.typeSymbol.isModule)) - new DocTemplateImpl(bSym, inTpl) with Object + new DocTemplateImpl(bSym, inTpl) with Object {} else if (bSym.isTrait || (bSym.isAliasType && bSym.tpe.typeSymbol.isTrait)) - new DocTemplateImpl(bSym, inTpl) with Trait + new DocTemplateImpl(bSym, inTpl) with Trait {} else if (bSym.isClass || (bSym.isAliasType && bSym.tpe.typeSymbol.isClass)) - new DocTemplateImpl(bSym, inTpl) with Class { - def valueParams = - // we don't want params on a class (non case class) signature - if (isCaseClass) primaryConstructor match { - case Some(const) => const.sym.paramss map (_ map (makeValueParam(_, this))) - case None => List() - } - else List.empty - val constructors = - members collect { case d: Constructor => d } - def primaryConstructor = constructors find { _.isPrimary } - } + new DocTemplateImpl(bSym, inTpl) with Class {} else - sys.error("'" + bSym + "' isn't a class, trait or object thus cannot be built as a documentable template") + sys.error("'" + bSym + "' isn't a class, trait or object thus cannot be built as a documentable template.") } val bSym = normalizeTemplate(aSym) @@ -638,7 +653,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { inTpl match { case inPkg: PackageImpl => val pack = new PackageImpl(bSym, inPkg) {} - if (pack.templates.isEmpty && pack.memberSymsLazy.isEmpty) + if (pack.templates.filter(_.isDocTemplate).isEmpty && pack.memberSymsLazy.isEmpty) droppedPackages += pack pack case _ => @@ -654,15 +669,22 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { /** * After the model is completed, no more DocTemplateEntities are created. * Therefore any symbol that still appears is: - * - NoDocTemplateMemberEntity (created here) + * - MemberTemplateEntity (created here) * - NoDocTemplateEntity (created in makeTemplate) */ def createLazyTemplateMember(aSym: Symbol, inTpl: DocTemplateImpl): MemberImpl = { // Code is duplicate because the anonymous classes are created statically - def createNoDocMemberTemplate(bSym: Symbol, inTpl: DocTemplateImpl): NoDocTemplateMemberImpl = { + def createNoDocMemberTemplate(bSym: Symbol, inTpl: DocTemplateImpl): MemberTemplateImpl = { assert(modelFinished) // only created AFTER the model is finished - new NoDocTemplateMemberImpl(bSym, inTpl) + if (bSym.isModule || (bSym.isAliasType && bSym.tpe.typeSymbol.isModule)) + new MemberTemplateImpl(bSym, inTpl) with Object {} + else if (bSym.isTrait || (bSym.isAliasType && bSym.tpe.typeSymbol.isTrait)) + new MemberTemplateImpl(bSym, inTpl) with Trait {} + else if (bSym.isClass || (bSym.isAliasType && bSym.tpe.typeSymbol.isClass)) + new MemberTemplateImpl(bSym, inTpl) with Class {} + else + sys.error("'" + bSym + "' isn't a class, trait or object thus cannot be built as a member template.") } assert(modelFinished) @@ -687,20 +709,18 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def makeRootPackage: PackageImpl = docTemplatesCache(RootPackage).asInstanceOf[PackageImpl] // TODO: Should be able to override the type - def makeMember(aSym: Symbol, implConv: ImplicitConversionImpl, inTpl: DocTemplateImpl): List[MemberImpl] = { + def makeMember(aSym: Symbol, conversion: Option[ImplicitConversionImpl], inTpl: DocTemplateImpl): List[MemberImpl] = { - def makeMember0(bSym: Symbol, _useCaseOf: Option[MemberImpl]): Option[MemberImpl] = { + def makeMember0(bSym: Symbol, useCaseOf: Option[MemberImpl]): Option[MemberImpl] = { if (bSym.isGetter && bSym.isLazy) - Some(new NonTemplateMemberImpl(bSym, implConv, inTpl) with Val { + Some(new NonTemplateMemberImpl(bSym, conversion, useCaseOf, inTpl) with Val { override lazy val comment = // The analyser does not duplicate the lazy val's DocDef when it introduces its accessor. thisFactory.comment(bSym.accessed, None, inTpl.asInstanceOf[DocTemplateImpl]) // This hack should be removed after analyser is fixed. override def isLazyVal = true - override def useCaseOf = _useCaseOf }) else if (bSym.isGetter && bSym.accessed.isMutable) - Some(new NonTemplateMemberImpl(bSym, implConv, inTpl) with Val { + Some(new NonTemplateMemberImpl(bSym, conversion, useCaseOf, inTpl) with Val { override def isVar = true - override def useCaseOf = _useCaseOf }) else if (bSym.isMethod && !bSym.hasAccessorFlag && !bSym.isConstructor && !bSym.isModule) { val cSym = { // This unsightly hack closes issue #4086. @@ -714,32 +734,30 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { } else bSym } - Some(new NonTemplateParamMemberImpl(cSym, implConv, inTpl) with HigherKindedImpl with Def { + Some(new NonTemplateParamMemberImpl(cSym, conversion, useCaseOf, inTpl) with HigherKindedImpl with Def { override def isDef = true - override def useCaseOf = _useCaseOf }) } - else if (bSym.isConstructor && (implConv == null)) - Some(new NonTemplateParamMemberImpl(bSym, implConv, inTpl) with Constructor { - override def isConstructor = true - def isPrimary = sym.isPrimaryConstructor - override def useCaseOf = _useCaseOf - }) + else if (bSym.isConstructor) + if (conversion.isDefined) + None // don't list constructors inherted by implicit conversion + else + Some(new NonTemplateParamMemberImpl(bSym, conversion, useCaseOf, inTpl) with Constructor { + override def isConstructor = true + def isPrimary = sym.isPrimaryConstructor + }) else if (bSym.isGetter) // Scala field accessor or Java field - Some(new NonTemplateMemberImpl(bSym, implConv, inTpl) with Val { + Some(new NonTemplateMemberImpl(bSym, conversion, useCaseOf, inTpl) with Val { override def isVal = true - override def useCaseOf = _useCaseOf }) else if (bSym.isAbstractType) - Some(new NonTemplateMemberImpl(bSym, implConv, inTpl) with TypeBoundsImpl with HigherKindedImpl with AbstractType { + Some(new MemberTemplateImpl(bSym, inTpl) with TypeBoundsImpl with AbstractType { override def isAbstractType = true - override def useCaseOf = _useCaseOf }) else if (bSym.isAliasType && bSym != AnyRefClass) - Some(new NonTemplateMemberImpl(bSym, implConv, inTpl) with HigherKindedImpl with AliasType { + Some(new MemberTemplateImpl(bSym, inTpl) with AliasType { override def isAliasType = true def alias = makeTypeInTemplateContext(sym.tpe.dealias, inTpl, sym) - override def useCaseOf = _useCaseOf }) else if (bSym.isPackage && !modelFinished) if (settings.skipPackage(makeQualifiedName(bSym))) None else @@ -822,7 +840,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { val arguments = { // lazy def noParams = annot.args map { _ => None } val params: List[Option[ValueParam]] = annotationClass match { - case aClass: Class => + case aClass: DocTemplateEntity with Class => (aClass.primaryConstructor map { _.valueParams.head }) match { case Some(vps) => vps map { Some(_) } case None => noParams diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala index bdae09e84d..00254df7ef 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala @@ -410,7 +410,7 @@ trait ModelFactoryImplicitSupport { // at the same time, the member itself is in the inTpl, not in the new template -- but should pick up // variables from the old template. Ugly huh? We'll always create the member inTpl, but it will change // the template when expanding variables in the comment :) - makeMember(aSym, this, inTpl) + makeMember(aSym, Some(this), inTpl) }) } diff --git a/src/partest/scala/tools/partest/ScaladocModelTest.scala b/src/partest/scala/tools/partest/ScaladocModelTest.scala index fc540f83fe..d8d5dfbbeb 100644 --- a/src/partest/scala/tools/partest/ScaladocModelTest.scala +++ b/src/partest/scala/tools/partest/ScaladocModelTest.scala @@ -106,20 +106,20 @@ abstract class ScaladocModelTest extends DirectTest { def _class(name: String): DocTemplateEntity = getTheFirst(_classes(name), tpl.qualifiedName + ".class(" + name + ")") def _classes(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case c: DocTemplateEntity with Class => c}) - def _classMbr(name: String): NoDocTemplateMemberEntity = getTheFirst(_classesMbr(name), tpl.qualifiedName + ".classMember(" + name + ")") - def _classesMbr(name: String): List[NoDocTemplateMemberEntity] = tpl.templates.filter(_.name == name).collect({ case c: NoDocTemplateMemberEntity if c.isClass => c}) + def _classMbr(name: String): MemberTemplateEntity = getTheFirst(_classesMbr(name), tpl.qualifiedName + ".classMember(" + name + ")") + def _classesMbr(name: String): List[MemberTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case c: MemberTemplateEntity if c.isClass => c}) def _trait(name: String): DocTemplateEntity = getTheFirst(_traits(name), tpl.qualifiedName + ".trait(" + name + ")") def _traits(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case t: DocTemplateEntity with Trait => t}) - def _traitMbr(name: String): NoDocTemplateMemberEntity = getTheFirst(_traitsMbr(name), tpl.qualifiedName + ".traitMember(" + name + ")") - def _traitsMbr(name: String): List[NoDocTemplateMemberEntity] = tpl.templates.filter(_.name == name).collect({ case t: NoDocTemplateMemberEntity if t.isTrait => t}) + def _traitMbr(name: String): MemberTemplateEntity = getTheFirst(_traitsMbr(name), tpl.qualifiedName + ".traitMember(" + name + ")") + def _traitsMbr(name: String): List[MemberTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case t: MemberTemplateEntity if t.isTrait => t}) def _object(name: String): DocTemplateEntity = getTheFirst(_objects(name), tpl.qualifiedName + ".object(" + name + ")") def _objects(name: String): List[DocTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case o: DocTemplateEntity with Object => o}) - def _objectMbr(name: String): NoDocTemplateMemberEntity = getTheFirst(_objectsMbr(name), tpl.qualifiedName + ".objectMember(" + name + ")") - def _objectsMbr(name: String): List[NoDocTemplateMemberEntity] = tpl.templates.filter(_.name == name).collect({ case o: NoDocTemplateMemberEntity if o.isObject => o}) + def _objectMbr(name: String): MemberTemplateEntity = getTheFirst(_objectsMbr(name), tpl.qualifiedName + ".objectMember(" + name + ")") + def _objectsMbr(name: String): List[MemberTemplateEntity] = tpl.templates.filter(_.name == name).collect({ case o: MemberTemplateEntity if o.isObject => o}) def _method(name: String): Def = getTheFirst(_methods(name), tpl.qualifiedName + ".method(" + name + ")") def _methods(name: String): List[Def] = tpl.methods.filter(_.name == name) diff --git a/test/scaladoc/run/diagrams-determinism.scala b/test/scaladoc/run/diagrams-determinism.scala index 6c8db05d78..2b6f8eecc7 100644 --- a/test/scaladoc/run/diagrams-determinism.scala +++ b/test/scaladoc/run/diagrams-determinism.scala @@ -49,19 +49,19 @@ object Test extends ScaladocModelTest { assert(run2 == run3) // 2. check the order in the diagram: this node, subclasses, and then implicit conversions - def assertRightOrder(diagram: Diagram) = { + def assertRightOrder(template: DocTemplateEntity, diagram: Diagram) = for ((node, subclasses) <- diagram.edges) assert(subclasses == subclasses.filter(_.isThisNode) ::: - subclasses.filter(_.isNormalNode) ::: - subclasses.filter(_.isImplicitNode)) - } + subclasses.filter(node => node.isNormalNode || node.isOutsideNode) ::: + subclasses.filter(_.isImplicitNode), + "Diagram order for " + template + ": " + subclasses) val base = rootPackage._package("scala")._package("test")._package("scaladoc")._package("diagrams") - assertRightOrder(base.contentDiagram.get) - assertRightOrder(base._trait("A").inheritanceDiagram.get) - assertRightOrder(base._trait("B").inheritanceDiagram.get) - assertRightOrder(base._trait("C").inheritanceDiagram.get) - assertRightOrder(base._trait("D").inheritanceDiagram.get) - assertRightOrder(base._trait("E").inheritanceDiagram.get) + assertRightOrder(base, base.contentDiagram.get) + assertRightOrder(base._trait("A"), base._trait("A").inheritanceDiagram.get) + assertRightOrder(base._trait("B"), base._trait("B").inheritanceDiagram.get) + assertRightOrder(base._trait("C"), base._trait("C").inheritanceDiagram.get) + assertRightOrder(base._trait("D"), base._trait("D").inheritanceDiagram.get) + assertRightOrder(base._trait("E"), base._trait("E").inheritanceDiagram.get) } } \ No newline at end of file diff --git a/test/scaladoc/run/diagrams-filtering.scala b/test/scaladoc/run/diagrams-filtering.scala index 8cb32180a1..54e3e9ac63 100644 --- a/test/scaladoc/run/diagrams-filtering.scala +++ b/test/scaladoc/run/diagrams-filtering.scala @@ -65,7 +65,7 @@ object Test extends ScaladocModelTest { assert(!C.inheritanceDiagram.isDefined) // trait G - val G = base._trait("G") + val G = base._class("G") assert(!G.inheritanceDiagram.isDefined) // trait E diff --git a/test/scaladoc/run/implicits-ambiguating.scala b/test/scaladoc/run/implicits-ambiguating.scala index 1420593b74..05daf1f805 100644 --- a/test/scaladoc/run/implicits-ambiguating.scala +++ b/test/scaladoc/run/implicits-ambiguating.scala @@ -17,7 +17,7 @@ object Test extends ScaladocModelTest { mbr.byConversion.map(_.source.implicitsShadowing.get(mbr).map(_.isAmbiguous).getOrElse(false)).getOrElse(false) // SEE THE test/resources/implicits-chaining-res.scala FOR THE EXPLANATION OF WHAT'S CHECKED HERE: - val base = root._package("scala")._package("test")._package("scaladoc")._package("implicits")._object("ambiguating") + val base = root._package("scala")._package("test")._package("scaladoc")._package("implicits")._package("ambiguating") var conv1: ImplicitConversion = null var conv2: ImplicitConversion = null diff --git a/test/scaladoc/run/implicits-shadowing.scala b/test/scaladoc/run/implicits-shadowing.scala index 2827d31122..6869b12a94 100644 --- a/test/scaladoc/run/implicits-shadowing.scala +++ b/test/scaladoc/run/implicits-shadowing.scala @@ -17,7 +17,7 @@ object Test extends ScaladocModelTest { mbr.byConversion.map(_.source.implicitsShadowing.get(mbr).map(_.isShadowed).getOrElse(false)).getOrElse(false) // SEE THE test/resources/implicits-chaining-res.scala FOR THE EXPLANATION OF WHAT'S CHECKED HERE: - val base = root._package("scala")._package("test")._package("scaladoc")._package("implicits")._object("shadowing") + val base = root._package("scala")._package("test")._package("scaladoc")._package("implicits")._package("shadowing") var conv: ImplicitConversion = null //// class A /////////////////////////////////////////////////////////////////////////////////////////////////////////// -- cgit v1.2.3 From dac4e8f543a8e2e3bacf447d327fc8a7e99acb49 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Mon, 16 Jul 2012 23:12:35 +0200 Subject: SI-5784 Scaladoc: {Abstract,Alias} type templates Normally scaladoc won't generate template pages for anything other than packages, classes, traits and objects. But using the @template annotation on {abstract,alias} types, they get their own page and take part as full members in the diagrams. Furthermore, when looking for the companion object, if a value of type T is in scope, T will be taken as the companion object (even though it might be a class) All templates, including types are listed on the left navigation pane, so now adding @template to String can get scaladoc to generate (a no-comments) page for java.lang.String. The {abstract, alias} type icons need to be updated -- I just took the class icons and added a small x to them -- but they shoud be something else (maybe an underscore?)i TO USE THIS PATCH: 
    /** @contentDiagram */ // tells scaladoc to create a diagram of the
                       // templates contained in trait Base
trait Base {
  /** @template */ // tells scaladoc to create a page for Foo
  type T < Foo
  trait Foo { def foo: Int }
}

/** @contentDiagram */
trait Api extends Base {
  /** @template */
  override type T <: FooApi
  trait FooApi extends Foo { def bar: String }
}
    --- src/compiler/scala/tools/ant/Scaladoc.scala | 2 +- src/compiler/scala/tools/nsc/doc/Settings.scala | 8 +- .../scala/tools/nsc/doc/html/HtmlFactory.scala | 7 +- .../scala/tools/nsc/doc/html/HtmlPage.scala | 4 +- .../tools/nsc/doc/html/page/ReferenceIndex.scala | 2 +- .../scala/tools/nsc/doc/html/page/Template.scala | 13 +- .../html/page/diagram/DotDiagramGenerator.scala | 12 ++ .../tools/nsc/doc/html/resource/lib/diagrams.css | 8 + .../scala/tools/nsc/doc/html/resource/lib/index.js | 48 +++--- .../doc/html/resource/lib/object_to_type_big.png | Bin 0 -> 9158 bytes .../scala/tools/nsc/doc/html/resource/lib/type.png | Bin 0 -> 3338 bytes .../tools/nsc/doc/html/resource/lib/type_big.png | Bin 0 -> 7691 bytes .../nsc/doc/html/resource/lib/type_diagram.png | Bin 0 -> 3895 bytes .../doc/html/resource/lib/type_to_object_big.png | Bin 0 -> 9054 bytes .../scala/tools/nsc/doc/model/Entity.scala | 10 +- .../scala/tools/nsc/doc/model/ModelFactory.scala | 181 +++++++++++++-------- .../nsc/doc/model/comment/CommentFactory.scala | 3 +- .../tools/nsc/doc/model/diagram/Diagram.scala | 4 +- .../nsc/doc/model/diagram/DiagramFactory.scala | 10 +- src/library-aux/scala/AnyRef.scala | 1 + .../scala/tools/partest/ScaladocModelTest.scala | 10 +- test/scaladoc/resources/SI-5784.scala | 28 ++++ test/scaladoc/resources/doc-root/AnyRef.scala | 1 + test/scaladoc/run/SI-5533.scala | 4 +- test/scaladoc/run/SI-5784.check | 1 + test/scaladoc/run/SI-5784.scala | 44 +++++ 26 files changed, 281 insertions(+), 120 deletions(-) create mode 100644 src/compiler/scala/tools/nsc/doc/html/resource/lib/object_to_type_big.png create mode 100644 src/compiler/scala/tools/nsc/doc/html/resource/lib/type.png create mode 100644 src/compiler/scala/tools/nsc/doc/html/resource/lib/type_big.png create mode 100644 src/compiler/scala/tools/nsc/doc/html/resource/lib/type_diagram.png create mode 100644 src/compiler/scala/tools/nsc/doc/html/resource/lib/type_to_object_big.png create mode 100644 test/scaladoc/resources/SI-5784.scala create mode 100644 test/scaladoc/run/SI-5784.check create mode 100644 test/scaladoc/run/SI-5784.scala (limited to 'src') diff --git a/src/compiler/scala/tools/ant/Scaladoc.scala b/src/compiler/scala/tools/ant/Scaladoc.scala index 61db3c7fa9..03cb770474 100644 --- a/src/compiler/scala/tools/ant/Scaladoc.scala +++ b/src/compiler/scala/tools/ant/Scaladoc.scala @@ -671,7 +671,7 @@ class Scaladoc extends ScalaMatchingTask { exception.printStackTrace() safeBuildError("Document failed because of an internal documenter error (" + exception.getMessage + "); see the error output for details.") - case exception => + case exception : Throwable => exception.printStackTrace() safeBuildError("Document failed because of an internal documenter error " + "(no error message provided); see the error output for details.") diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala index 7cb539feee..7662381186 100644 --- a/src/compiler/scala/tools/nsc/doc/Settings.scala +++ b/src/compiler/scala/tools/nsc/doc/Settings.scala @@ -183,6 +183,11 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) "" ) + val docExpandAllTypes = BooleanSetting ( + "-expand-all-types", + "Expand all type aliases and abstract types into full template pages. (locally this can be done with the @template annotation)" + ) + // Somewhere slightly before r18708 scaladoc stopped building unless the // self-type check was suppressed. I hijacked the slotted-for-removal-anyway // suppress-vt-warnings option and renamed it for this purpose. @@ -195,7 +200,8 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) docDiagramsDotTimeout, docDiagramsDotRestart, docImplicits, docImplicitsDebug, docImplicitsShowAll, docDiagramsMaxNormalClasses, docDiagramsMaxImplicitClasses, - docNoPrefixes, docNoLinkWarnings, docRawOutput, docSkipPackages + docNoPrefixes, docNoLinkWarnings, docRawOutput, docSkipPackages, + docExpandAllTypes ) val isScaladocSpecific: String => Boolean = scaladocSpecific map (_.name) diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala index 18cc65092b..436425df83 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala @@ -53,11 +53,16 @@ class HtmlFactory(val universe: doc.Universe, index: doc.Index) { "trait.png", "trait_big.png", "trait_diagram.png", + "type.png", + "type_big.png", + "type_diagram.png", "class_to_object_big.png", "object_to_class_big.png", - "object_to_trait_big.png", "trait_to_object_big.png", + "object_to_trait_big.png", + "type_to_object_big.png", + "object_to_type_big.png", "arrow-down.png", "arrow-right.png", diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala index 226ed49aca..aa2df57967 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala @@ -211,10 +211,12 @@ abstract class HtmlPage extends Page { thisPage => else if (ety.isTrait) "trait_big.png" else if (ety.isClass && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None) "class_to_object_big.png" else if (ety.isClass) "class_big.png" + else if ((ety.isAbstractType || ety.isAliasType) && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None) "type_to_object_big.png" + else if ((ety.isAbstractType || ety.isAliasType)) "type_big.png" else if (ety.isObject && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None && ety.companion.get.isClass) "object_to_class_big.png" else if (ety.isObject && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None && ety.companion.get.isTrait) "object_to_trait_big.png" + else if (ety.isObject && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None && (ety.companion.get.isAbstractType || ety.companion.get.isAliasType)) "object_to_trait_big.png" else if (ety.isObject) "object_big.png" else if (ety.isPackage) "package_big.png" else "class_big.png" // FIXME: an entity *should* fall into one of the above categories, but AnyRef is somehow not - } diff --git a/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala b/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala index a76cc231b4..effaee711d 100755 --- a/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala @@ -34,7 +34,7 @@ class ReferenceIndex(letter: Char, index: doc.Index, universe: Universe) extends } else { html } - }) + }).toList.distinct
    { 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 d691692920..487ef447e9 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -92,7 +92,7 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp

    { templatesToHtml(tpl.inTemplate.toRoot.reverse.tail, xml.Text(".")) }

    } - +
    { tpl.companion match { @@ -734,20 +734,21 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp } }{ if (isReduced) NodeSeq.Empty else { mbr match { - case tpl: DocTemplateEntity if !tpl.parentTypes.isEmpty => - extends { typeToHtml(tpl.parentTypes.map(_._2), hasLinks) } - case tme: MemberEntity if (tme.isDef || tme.isVal || tme.isLazyVal || tme.isVar) => : { typeToHtml(tme.resultType, hasLinks) } - case abt: AbstractType => + case abt: MemberEntity with AbstractType => val b2s = boundsToHtml(abt.hi, abt.lo, hasLinks) if (b2s != NodeSeq.Empty) { b2s } else NodeSeq.Empty - case alt: AliasType => + case alt: MemberEntity with AliasType => = { typeToHtml(alt.alias, hasLinks) } + + case tpl: MemberTemplateEntity if !tpl.parentTypes.isEmpty => + extends { typeToHtml(tpl.parentTypes.map(_._2), hasLinks) } + case _ => NodeSeq.Empty } }} 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 f3454f71b8..bae61f1a3b 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 @@ -242,6 +242,8 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { attr ++= classStyle else if(node.isObjectNode) attr ++= objectStyle + else if(node.isTypeNode) + attr ++= typeStyle else attr ++= defaultStyle @@ -254,6 +256,8 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { img = "class_diagram.png" else if(node.isObjectNode) img = "object_diagram.png" + else if(node.isTypeNode) + img = "type_diagram.png" if(!img.equals("")) { img = "" @@ -307,6 +311,8 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { space + "trait" else if (node.isObjectNode) space + "object" + else if (node.isTypeNode) + space + "type" else default @@ -491,6 +497,12 @@ class DotDiagramGenerator(settings: doc.Settings) extends DiagramGenerator { "fontcolor" -> "#ffffff" ) + private val typeStyle = Map( + "color" -> "#115F3B", + "fillcolor" -> "#0A955B", + "fontcolor" -> "#ffffff" + ) + private def flatten(attributes: Map[String, String]) = attributes.map{ case (key, value) => key + "=\"" + value + "\"" }.mkString(", ") private val graphAttributesStr = graphAttributes.map{ case (key, value) => key + "=\"" + value + "\";\n" }.mkString diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/diagrams.css b/src/compiler/scala/tools/nsc/doc/html/resource/lib/diagrams.css index 04d29580b7..5fe33f72f5 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/diagrams.css +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/diagrams.css @@ -119,6 +119,14 @@ svg.class-diagram .node.this.trait.over polygon fill: #235d7b; } +svg.package-diagram .node.type.over polygon, +svg.class-diagram .node.this.type.over polygon +{ + fill: #098552; + fill: #04663e; +} + + svg.package-diagram .node.object.over polygon { fill: #183377; diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/index.js b/src/compiler/scala/tools/nsc/doc/html/resource/lib/index.js index eb7f752440..f29438edfb 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/index.js +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/index.js @@ -15,15 +15,15 @@ var lastHash = ""; $(document).ready(function() { $('body').layout({ west__size: '20%' }); - $('#browser').layout({ + $('#browser').layout({ center__paneSelector: ".ui-west-center" //,center__initClosed:true ,north__paneSelector: ".ui-west-north" - }); + }); $('iframe').bind("load", function(){ var subtitle = $(this).contents().find('title').text(); $(document).attr('title', (title ? title + " - " : "") + subtitle); - + setUrlFragmentFromFrameSrc(); }); @@ -81,16 +81,16 @@ function setUrlFragmentFromFrameSrc() { var commonLength = location.pathname.lastIndexOf("/"); var frameLocation = frames["template"].location; var relativePath = frameLocation.pathname.slice(commonLength + 1); - + if(!relativePath || frameLocation.pathname.indexOf("/") < 0) return; - + // Add #, remove ".html" and replace "/" with "." fragment = "#" + relativePath.replace(/\.html$/, "").replace(/\//g, "."); - + // Add the frame's hash after an @ if(frameLocation.hash) fragment += ("@" + frameLocation.hash.slice(1)); - + // Use replace to not add history items lastFragment = fragment; location.replace(fragment); @@ -109,7 +109,7 @@ var Index = {}; if (type == 'object') { href = t['object']; } else { - href = t['class'] || t['trait'] || t['case class']; + href = t['class'] || t['trait'] || t['case class'] || t['type']; } return [ '' : ''; - inner += openLink(template, template['trait'] ? 'trait' : 'class'); + inner += openLink(template, template['trait'] ? 'trait' : template['type'] ? 'type' : 'class'); } else { inner += '
    '; } @@ -245,6 +245,7 @@ function configureEntityList() { function prepareEntityList() { var classIcon = $("#library > img.class"); var traitIcon = $("#library > img.trait"); + var typeIcon = $("#library > img.type"); var objectIcon = $("#library > img.object"); var packageIcon = $("#library > img.package"); @@ -252,6 +253,7 @@ function prepareEntityList() { $('#tpl li.pack').each(function () { $("span.class", this).each(function() { $(this).replaceWith(classIcon.clone()); }); $("span.trait", this).each(function() { $(this).replaceWith(traitIcon.clone()); }); + $("span.type", this).each(function() { $(this).replaceWith(typeIcon.clone()); }); $("span.object", this).each(function() { $(this).replaceWith(objectIcon.clone()); }); $("span.package", this).each(function() { $(this).replaceWith(packageIcon.clone()); }); }); @@ -265,11 +267,11 @@ function keyboardScrolldownLeftPane() { scheduler.add("init", function() { $("#textfilter input").blur(); var $items = $("#tpl li"); - $items.first().addClass('selected'); + $items.first().addClass('selected'); $(window).bind("keydown", function(e) { var $old = $items.filter('.selected'), - $new; + $new; switch ( e.keyCode ) { @@ -286,7 +288,7 @@ function keyboardScrolldownLeftPane() { case 27: // escape $old.removeClass('selected'); $(window).unbind(e); - $("#textfilter input").focus(); + $("#textfilter input").focus(); break; @@ -296,7 +298,7 @@ function keyboardScrolldownLeftPane() { if (!$new.length) { $new = $old.parent().prev(); } - + if ($new.is('ol') && $new.children(':last').is('ol')) { $new = $new.children().children(':last'); } else if ($new.is('ol')) { @@ -313,17 +315,17 @@ function keyboardScrolldownLeftPane() { if ($new.is('ol')) { $new = $new.children(':first'); } - break; - } - + break; + } + if ($new.is('li')) { $old.removeClass('selected'); - $new.addClass('selected'); + $new.addClass('selected'); } else if (e.keyCode == 38) { $(window).unbind(e); $("#textfilter input").focus(); } - }); + }); }); } @@ -342,13 +344,13 @@ function configureTextFilter() { $("#template").contents().find("#mbrsel-input").focus(); input.attr("value", ""); return false; - } + } if (event.keyCode == 40) { // down arrow $(window).unbind("keydown"); keyboardScrolldownLeftPane(); return false; - } - textFilter(); + } + textFilter(); }); input.focus(function(event) { input.select(); }); }); @@ -419,7 +421,7 @@ function textFilter() { }); configureHideFilter(); }; - + scheduler.add('filter', searchLoop); } diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/object_to_type_big.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/object_to_type_big.png new file mode 100644 index 0000000000..7502942eb6 Binary files /dev/null and b/src/compiler/scala/tools/nsc/doc/html/resource/lib/object_to_type_big.png differ diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type.png new file mode 100644 index 0000000000..366ec4e992 Binary files /dev/null and b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type.png differ diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_big.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_big.png new file mode 100644 index 0000000000..df0dc118bf Binary files /dev/null and b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_big.png differ diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_diagram.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_diagram.png new file mode 100644 index 0000000000..d6fbb84ff2 Binary files /dev/null and b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_diagram.png differ diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_to_object_big.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_to_object_big.png new file mode 100644 index 0000000000..1bd2833a63 Binary files /dev/null and b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_to_object_big.png differ diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index 620aa4253f..0836d7e4da 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -241,6 +241,11 @@ trait MemberTemplateEntity extends TemplateEntity with MemberEntity with HigherK /** The value parameters of this case class, or an empty list if this class is not a case class. As case class value * parameters cannot be curried, the outer list has exactly one element. */ def valueParams: List[List[ValueParam]] + + /** The direct super-type of this template + e.g: {{{class A extends B[C[Int]] with D[E]}}} will have two direct parents: class B and D + NOTE: we are dropping the refinement here! */ + def parentTypes: List[(TemplateEntity, TypeEntity)] } /** A template (class, trait, object or package) for which documentation is available. Only templates for which @@ -259,11 +264,6 @@ trait DocTemplateEntity extends MemberTemplateEntity { * only if the `docsourceurl` setting has been set. */ def sourceUrl: Option[java.net.URL] - /** The direct super-type of this template - e.g: {{{class A extends B[C[Int]] with D[E]}}} will have two direct parents: class B and D - NOTE: we are dropping the refinement here! */ - def parentTypes: 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] diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index fc5fde3239..0ba32fceaa 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -265,6 +265,32 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { override def isNoDocMemberTemplate = true lazy val definitionName = optimize(inDefinitionTemplates.head.qualifiedName + "." + name) def valueParams: List[List[ValueParam]] = Nil /** TODO, these are now only computed for DocTemplates */ + + // Seems unused + // def parentTemplates = + // if (sym.isPackage || sym == AnyClass) + // List() + // else + // sym.tpe.parents.flatMap { tpe: Type => + // val tSym = tpe.typeSymbol + // if (tSym != NoSymbol) + // List(makeTemplate(tSym)) + // else + // List() + // } filter (_.isInstanceOf[DocTemplateEntity]) + + def parentTypes = + if (sym.isPackage || sym == AnyClass) List() else { + val tps = (this match { + case a: AliasType => sym.tpe.dealias.parents + case a: AbstractType => sym.info.bounds match { + case TypeBounds(lo, hi) => List(hi) + case _ => Nil + } + case _ => sym.tpe.parents + }) map { _.asSeenFrom(sym.thisType, sym) } + makeParentTypes(RefinedType(tps, EmptyScope), Some(this), inTpl) + } } /** The instantiation of `TemplateImpl` triggers the creation of the following entities: @@ -306,24 +332,6 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { else None } - def parentTemplates = - if (sym.isPackage || sym == AnyClass) - List() - else - sym.tpe.parents.flatMap { tpe: Type => - val tSym = tpe.typeSymbol - if (tSym != NoSymbol) - List(makeTemplate(tSym)) - else - List() - } filter (_.isInstanceOf[DocTemplateEntity]) - - def parentTypes = - if (sym.isPackage || sym == AnyClass) List() else { - val tps = sym.tpe.parents map { _.asSeenFrom(sym.thisType, sym) } - makeParentTypes(RefinedType(tps, EmptyScope), Some(this), inTpl) - } - protected def linearizationFromSymbol(symbol: Symbol): List[(TemplateEntity, TypeEntity)] = { symbol.ancestors map { ancestor => val typeEntity = makeType(symbol.info.baseType(ancestor), this) @@ -378,7 +386,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { // the direct members (methods, values, vars, types and directly contained templates) var memberSymsEager = memberSyms.filter(!memberSymsLazy.contains(_)) // the members generated by the symbols in memberSymsEager - val ownMembers = (memberSyms.flatMap(makeMember(_, None, this))) + val ownMembers = (memberSymsEager.flatMap(makeMember(_, None, this))) // all the members that are documentented PLUS the members inherited by implicit conversions var members: List[MemberImpl] = ownMembers @@ -395,11 +403,13 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { */ def completeModel: Unit = { // DFS completion - for (member <- members) - member match { - case d: DocTemplateImpl => d.completeModel - case _ => - } + // since alias types and abstract types have no own members, there's no reason for them to call completeModel + if (!sym.isAliasType && !sym.isAbstractType) + for (member <- members) + member match { + case d: DocTemplateImpl => d.completeModel + case _ => + } members :::= memberSymsLazy.map(modelCreation.createLazyTemplateMember(_, this)) @@ -432,15 +442,33 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { override def isTemplate = true override def isDocTemplate = true - def companion = sym.companionSymbol match { - case NoSymbol => None - case comSym if !isEmptyJavaObject(comSym) && (comSym.isClass || comSym.isModule) => - makeTemplate(comSym) match { - case d: DocTemplateImpl => Some(d) - case _ => None + private[this] lazy val companionSymbol = + if (sym.isAliasType || sym.isAbstractType) { + inTpl.sym.info.member(sym.name.toTermName) match { + case NoSymbol => NoSymbol + case s => + s.info match { + case ot: OverloadedType => + NoSymbol + case _ => + // that's to navigate from val Foo: FooExtractor to FooExtractor :) + s.info.resultType.typeSymbol + } } - case _ => None - } + } + else + sym.companionSymbol + + def companion = + companionSymbol match { + case NoSymbol => None + case comSym if !isEmptyJavaObject(comSym) && (comSym.isClass || comSym.isModule) => + makeTemplate(comSym) match { + case d: DocTemplateImpl => Some(d) + case _ => None + } + case _ => None + } def constructors: List[MemberImpl with Constructor] = if (isClass) members collect { case d: Constructor => d } else Nil def primaryConstructor: Option[MemberImpl with Constructor] = if (isClass) constructors find { _.isPrimary } else None @@ -523,6 +551,12 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { val name = optimize(sym.nameString) } + private trait AliasImpl { + def sym: Symbol + def inTpl: TemplateImpl + def alias = makeTypeInTemplateContext(sym.tpe.dealias, inTpl, sym) + } + private trait TypeBoundsImpl { def sym: Symbol def inTpl: TemplateImpl @@ -591,13 +625,16 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def createRootPackage: PackageImpl = docTemplatesCache.get(RootPackage) match { case Some(root: PackageImpl) => root - case _ => modelCreation.createTemplate(RootPackage, null).asInstanceOf[PackageImpl] + case _ => modelCreation.createTemplate(RootPackage, null) match { + case Some(root: PackageImpl) => root + case _ => sys.error("Scaladoc: Unable to create root package!") + } } /** * Create a template, either a package, class, trait or object */ - def createTemplate(aSym: Symbol, inTpl: DocTemplateImpl): DocTemplateImpl = { + def createTemplate(aSym: Symbol, inTpl: DocTemplateImpl): Option[MemberImpl] = { // don't call this after the model finished! assert(!modelFinished) @@ -616,11 +653,15 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { def createDocTemplate(bSym: Symbol, inTpl: DocTemplateImpl): DocTemplateImpl = { assert(!modelFinished) // only created BEFORE the model is finished - if (bSym.isModule || (bSym.isAliasType && bSym.tpe.typeSymbol.isModule)) + if (bSym.isAliasType && bSym != AnyRefClass) + new DocTemplateImpl(bSym, inTpl) with AliasImpl with AliasType { override def isAliasType = true } + else if (bSym.isAbstractType) + new DocTemplateImpl(bSym, inTpl) with TypeBoundsImpl with AbstractType { override def isAbstractType = true } + else if (bSym.isModule) new DocTemplateImpl(bSym, inTpl) with Object {} - else if (bSym.isTrait || (bSym.isAliasType && bSym.tpe.typeSymbol.isTrait)) + else if (bSym.isTrait) new DocTemplateImpl(bSym, inTpl) with Trait {} - else if (bSym.isClass || (bSym.isAliasType && bSym.tpe.typeSymbol.isClass)) + else if (bSym.isClass || bSym == AnyRefClass) new DocTemplateImpl(bSym, inTpl) with Class {} else sys.error("'" + bSym + "' isn't a class, trait or object thus cannot be built as a documentable template.") @@ -628,7 +669,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { val bSym = normalizeTemplate(aSym) if (docTemplatesCache isDefinedAt bSym) - return docTemplatesCache(bSym) + return Some(docTemplatesCache(bSym)) /* Three cases of templates: * (1) root package -- special cased for bootstrapping @@ -636,7 +677,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { * (3) class/object/trait */ if (bSym == RootPackage) // (1) - new RootPackageImpl(bSym) { + Some(new RootPackageImpl(bSym) { override lazy val comment = createRootPackageComment override val name = "root" override def inTemplate = this @@ -648,21 +689,28 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { (bSym.info.members ++ EmptyPackage.info.members) filter { s => s != EmptyPackage && s != RootPackage } - } + }) else if (bSym.isPackage) // (2) - inTpl match { - case inPkg: PackageImpl => - val pack = new PackageImpl(bSym, inPkg) {} - if (pack.templates.filter(_.isDocTemplate).isEmpty && pack.memberSymsLazy.isEmpty) - droppedPackages += pack - pack - case _ => - sys.error("'" + bSym + "' must be in a package") - } + if (settings.skipPackage(makeQualifiedName(bSym))) + None + else + inTpl match { + case inPkg: PackageImpl => + val pack = new PackageImpl(bSym, inPkg) {} + // Used to check package pruning works: + //println(pack.qualifiedName) + if (pack.templates.filter(_.isDocTemplate).isEmpty && pack.memberSymsLazy.isEmpty) { + droppedPackages += pack + None + } else + Some(pack) + case _ => + sys.error("'" + bSym + "' must be in a package") + } else { // no class inheritance at this point - assert(inOriginalOwner(bSym, inTpl)) - createDocTemplate(bSym, inTpl) + assert(inOriginalOwner(bSym, inTpl) || bSym.isAbstractType || bSym.isAliasType, bSym + " in " + inTpl) + Some(createDocTemplate(bSym, inTpl)) } } @@ -750,28 +798,16 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { Some(new NonTemplateMemberImpl(bSym, conversion, useCaseOf, inTpl) with Val { override def isVal = true }) - else if (bSym.isAbstractType) + else if (bSym.isAbstractType && !typeShouldDocument(bSym, inTpl)) Some(new MemberTemplateImpl(bSym, inTpl) with TypeBoundsImpl with AbstractType { override def isAbstractType = true }) - else if (bSym.isAliasType && bSym != AnyRefClass) - Some(new MemberTemplateImpl(bSym, inTpl) with AliasType { + else if (bSym.isAliasType && !typeShouldDocument(bSym, inTpl)) + Some(new MemberTemplateImpl(bSym, inTpl) with AliasImpl with AliasType { override def isAliasType = true - def alias = makeTypeInTemplateContext(sym.tpe.dealias, inTpl, sym) }) - else if (bSym.isPackage && !modelFinished) - if (settings.skipPackage(makeQualifiedName(bSym))) None else - inTpl match { - case inPkg: PackageImpl => modelCreation.createTemplate(bSym, inTpl) match { - case p: PackageImpl if droppedPackages contains p => None - case p: PackageImpl => Some(p) - case _ => sys.error("'" + bSym + "' must be a package") - } - case _ => - sys.error("'" + bSym + "' must be in a package") - } - else if (!modelFinished && templateShouldDocument(bSym, inTpl) && inOriginalOwner(bSym, inTpl)) - Some(modelCreation.createTemplate(bSym, inTpl)) + else if (!modelFinished && (bSym.isPackage || bSym.isAliasType || bSym.isAbstractType || templateShouldDocument(bSym, inTpl))) + modelCreation.createTemplate(bSym, inTpl) else None } @@ -915,7 +951,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { } /** Get the types of the parents of the current class, ignoring the refinements */ - def makeParentTypes(aType: Type, tpl: Option[DocTemplateImpl], inTpl: TemplateImpl): List[(TemplateEntity, TypeEntity)] = aType match { + def makeParentTypes(aType: Type, tpl: Option[MemberTemplateImpl], inTpl: TemplateImpl): List[(TemplateEntity, TypeEntity)] = aType match { case RefinedType(parents, defs) => val ignoreParents = Set[Symbol](AnyClass, AnyRefClass, ObjectClass) val filtParents = @@ -978,7 +1014,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { normalizeTemplate(aSym.owner) == normalizeTemplate(inTpl.sym) def templateShouldDocument(aSym: Symbol, inTpl: TemplateImpl): Boolean = - (aSym.isClass || aSym.isModule || aSym == AnyRefClass) && + (aSym.isTrait || aSym.isClass || aSym.isModule) && localShouldDocument(aSym) && !isEmptyJavaObject(aSym) && // either it's inside the original owner or we can document it later: @@ -1014,5 +1050,10 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { // the implicit conversions that are excluded from the pages should not appear in the diagram def implicitExcluded(convertorMethod: String): Boolean = settings.hardcoded.commonConversionTargets.contains(convertorMethod) + + // whether or not to create a page for an {abstract,alias} type + def typeShouldDocument(bSym: Symbol, inTpl: DocTemplateImpl) = + (settings.docExpandAllTypes.value && (bSym.sourceFile != null)) || + global.expandedDocComment(bSym, inTpl.sym).contains("@template") } diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala index df913555a7..a57ccd36c2 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala @@ -350,7 +350,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory with Member case None => List.empty } - val tagsWithoutDiagram = tags.filterNot(pair => pair._1 == inheritDiagramTag || pair._1 == contentDiagramTag) + val stripTags=List(inheritDiagramTag, contentDiagramTag, SimpleTagKey("template")) + val tagsWithoutDiagram = tags.filterNot(pair => stripTags.contains(pair._1)) val bodyTags: mutable.Map[TagKey, List[Body]] = mutable.Map(tagsWithoutDiagram mapValues {tag => tag map (parseWiki(_, pos, inTplOpt))} toSeq: _*) 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 902d5da240..c2aa1f17f3 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/Diagram.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/Diagram.scala @@ -70,7 +70,8 @@ abstract class Node { def isClassNode = if (tpl.isDefined) (tpl.get.isClass || tpl.get.qualifiedName == "scala.AnyRef") else false def isTraitNode = if (tpl.isDefined) tpl.get.isTrait else false def isObjectNode= if (tpl.isDefined) tpl.get.isObject else false - def isOtherNode = !(isClassNode || isTraitNode || isObjectNode) + def isTypeNode = if (doctpl.isDefined) doctpl.get.isAbstractType || doctpl.get.isAliasType else false + def isOtherNode = !(isClassNode || isTraitNode || isObjectNode || isTypeNode) def isImplicitNode = false def isOutsideNode = false def tooltip: Option[String] @@ -91,6 +92,7 @@ abstract class Node { object Node { def unapply(n: Node): Option[(TypeEntity, Option[TemplateEntity])] = Some((n.tpe, n.tpl)) } object ClassNode { def unapply(n: Node): Option[(TypeEntity, Option[TemplateEntity])] = if (n.isClassNode) Some((n.tpe, n.tpl)) else None } object TraitNode { def unapply(n: Node): Option[(TypeEntity, Option[TemplateEntity])] = if (n.isTraitNode) Some((n.tpe, n.tpl)) else None } +object TypeNode { def unapply(n: Node): Option[(TypeEntity, Option[TemplateEntity])] = if (n.isTypeNode) Some((n.tpe, n.tpl)) else None } object ObjectNode { def unapply(n: Node): Option[(TypeEntity, Option[TemplateEntity])] = if (n.isObjectNode) Some((n.tpe, n.tpl)) else None } object OutsideNode { def unapply(n: Node): Option[(TypeEntity, Option[TemplateEntity])] = if (n.isOutsideNode) Some((n.tpe, n.tpl)) else None } object OtherNode { def unapply(n: Node): Option[(TypeEntity, Option[TemplateEntity])] = if (n.isOtherNode) Some((n.tpe, n.tpl)) else None } 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 e0f6d42a68..2645d8fd14 100644 --- a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala @@ -121,12 +121,10 @@ trait DiagramFactory extends DiagramDirectiveParser { // for each node, add its subclasses for (node <- nodesAll if !classExcluded(node)) { node match { - case dnode: DocTemplateImpl => - var superClasses = dnode.parentTypes.map(_._1) + case dnode: MemberTemplateImpl => + var superClasses = dnode.parentTypes.map(_._1).filter(nodesAll.contains(_)) - superClasses = superClasses.filter(nodesAll.contains(_)) - - // TODO: Everyone should be able to use the @{inherit,content}Diagram annotation to change the diagrams. + // TODO: Everyone should be able to use the @{inherit,content}Diagram annotation to add nodes to diagrams. if (pack.sym == ScalaPackage) if (dnode.sym == NullClass) superClasses = List(makeTemplate(AnyRefClass)) @@ -142,7 +140,7 @@ trait DiagramFactory extends DiagramDirectiveParser { } mapNodes += node -> ( - if (node.inTemplate == pack && !node.isNoDocMemberTemplate) + if (node.inTemplate == pack && (node.isDocTemplate || node.isAbstractType || node.isAliasType)) NormalNode(node.resultType, Some(node))() else OutsideNode(node.resultType, Some(node))() diff --git a/src/library-aux/scala/AnyRef.scala b/src/library-aux/scala/AnyRef.scala index 1eefb0c806..7d8b9f9e76 100644 --- a/src/library-aux/scala/AnyRef.scala +++ b/src/library-aux/scala/AnyRef.scala @@ -10,6 +10,7 @@ package scala /** Class `AnyRef` is the root class of all ''reference types''. * All types except the value types descend from this class. + * @template */ trait AnyRef extends Any { diff --git a/src/partest/scala/tools/partest/ScaladocModelTest.scala b/src/partest/scala/tools/partest/ScaladocModelTest.scala index d8d5dfbbeb..adf7abe11c 100644 --- a/src/partest/scala/tools/partest/ScaladocModelTest.scala +++ b/src/partest/scala/tools/partest/ScaladocModelTest.scala @@ -130,11 +130,17 @@ abstract class ScaladocModelTest extends DirectTest { def _conversion(name: String): ImplicitConversion = getTheFirst(_conversions(name), tpl.qualifiedName + ".conversion(" + name + ")") def _conversions(name: String): List[ImplicitConversion] = tpl.conversions.filter(_.conversionQualifiedName == name) - def _absType(name: String): MemberEntity = getTheFirst(_methods(name), tpl.qualifiedName + ".abstractType(" + name + ")") + def _absType(name: String): MemberEntity = getTheFirst(_absTypes(name), tpl.qualifiedName + ".abstractType(" + name + ")") def _absTypes(name: String): List[MemberEntity] = tpl.members.filter(mbr => mbr.name == name && mbr.isAbstractType) - def _aliasType(name: String): MemberEntity = getTheFirst(_methods(name), tpl.qualifiedName + ".aliasType(" + name + ")") + def _absTypeTpl(name: String): DocTemplateEntity = getTheFirst(_absTypeTpls(name), tpl.qualifiedName + ".abstractType(" + name + ")") + def _absTypeTpls(name: String): List[DocTemplateEntity] = tpl.members.collect({ case dtpl: DocTemplateEntity with AbstractType if dtpl.name == name => dtpl }) + + def _aliasType(name: String): MemberEntity = getTheFirst(_aliasTypes(name), tpl.qualifiedName + ".aliasType(" + name + ")") def _aliasTypes(name: String): List[MemberEntity] = tpl.members.filter(mbr => mbr.name == name && mbr.isAliasType) + + def _aliasTypeTpl(name: String): DocTemplateEntity = getTheFirst(_aliasTypeTpls(name), tpl.qualifiedName + ".aliasType(" + name + ")") + def _aliasTypeTpls(name: String): List[DocTemplateEntity] = tpl.members.collect({ case dtpl: DocTemplateEntity with AliasType if dtpl.name == name => dtpl }) } class PackageAccess(pack: Package) extends TemplateAccess(pack) { diff --git a/test/scaladoc/resources/SI-5784.scala b/test/scaladoc/resources/SI-5784.scala new file mode 100644 index 0000000000..175cc3cf33 --- /dev/null +++ b/test/scaladoc/resources/SI-5784.scala @@ -0,0 +1,28 @@ +package test.templates { + object `package` { + /** @template */ + type String = java.lang.String + val String = new StringCompanion + class StringCompanion { def boo = ??? } + } + + /** @contentDiagram */ + trait Base { + /** @template */ + type String = test.templates.String + /** @template + * @inheritanceDiagram */ + type T <: Foo + val T: FooExtractor + trait Foo { def foo: Int } + trait FooExtractor { def apply(foo: Int); def unapply(t: Foo): Option[Int] } + } + + /** @contentDiagram */ + trait Api extends Base { + /** @template + * @inheritanceDiagram */ + override type T <: FooApi + trait FooApi extends Foo { def bar: String } + } +} diff --git a/test/scaladoc/resources/doc-root/AnyRef.scala b/test/scaladoc/resources/doc-root/AnyRef.scala index 1eefb0c806..7d8b9f9e76 100644 --- a/test/scaladoc/resources/doc-root/AnyRef.scala +++ b/test/scaladoc/resources/doc-root/AnyRef.scala @@ -10,6 +10,7 @@ package scala /** Class `AnyRef` is the root class of all ''reference types''. * All types except the value types descend from this class. + * @template */ trait AnyRef extends Any { diff --git a/test/scaladoc/run/SI-5533.scala b/test/scaladoc/run/SI-5533.scala index e7b5f57860..989d9aa13a 100644 --- a/test/scaladoc/run/SI-5533.scala +++ b/test/scaladoc/run/SI-5533.scala @@ -32,6 +32,8 @@ object Test extends ScaladocModelTest { val B = b._class("B") val D = b._class("D") testDiagram(B, B.contentDiagram, 2, 1) - testDiagram(D, D.contentDiagram, 2, 1) + // unfortunately not all packages, as B1 extends A.this.A1 and it gets the wrong member -- maybe we should model + // things as we do for symbols? + testDiagram(D, D.contentDiagram, 3, 2) } } \ No newline at end of file diff --git a/test/scaladoc/run/SI-5784.check b/test/scaladoc/run/SI-5784.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/SI-5784.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/SI-5784.scala b/test/scaladoc/run/SI-5784.scala new file mode 100644 index 0000000000..318eb78b2a --- /dev/null +++ b/test/scaladoc/run/SI-5784.scala @@ -0,0 +1,44 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def resourceFile: String = "SI-5784.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._ + + val main = rootPackage._package("test")._package("templates") + + val String = main._aliasTypeTpl("String") + assert(String.companion.isDefined, "test.templates.String should have a pseudo-companion object") + + val Base = main._trait("Base") + assert(Base.members.filter(_.inDefinitionTemplates.head == Base).length == 5, Base.members.filter(_.inDefinitionTemplates.head == Base).length + " == 5") + assert(Base.members.collect{case d: DocTemplateEntity => d}.length == 4, Base.members.collect{case d: DocTemplateEntity => d}.length == 4) + testDiagram(Base, Base.contentDiagram, 2, 1) + + val BaseT = Base._absTypeTpl("T") + val Foo = Base._trait("Foo") + assert(BaseT.members.filter(_.inDefinitionTemplates.head == Base).length == 0, BaseT.members.filter(_.inDefinitionTemplates.head == Base).length + " == 0") + assert(BaseT.members.map(_.name).sorted == Foo.members.map(_.name).sorted, BaseT.members.map(_.name).sorted + " == " + Foo.members.map(_.name).sorted) + assert(BaseT.companion.isDefined, "test.templates.Base.T should have a pseudo-companion object") + testDiagram(BaseT, BaseT.inheritanceDiagram, 2, 1) + + val Api = main._trait("Api") + assert(Api.members.filter(_.inDefinitionTemplates.head == Api).length == 2, Api.members.filter(_.inDefinitionTemplates.head == Api).length + " == 2") // FooApi and override type T + assert(Api.members.collect{case d: DocTemplateEntity => d}.length == 5, Api.members.collect{case d: DocTemplateEntity => d}.length == 5) + testDiagram(Api, Api.contentDiagram, 3, 2) + + val ApiT = Api._absTypeTpl("T") + val FooApi = Api._trait("FooApi") + assert(ApiT.members.filter(_.inDefinitionTemplates.head == Api).length == 0, ApiT.members.filter(_.inDefinitionTemplates.head == Api).length + " == 0") + assert(ApiT.members.map(_.name).sorted == FooApi.members.map(_.name).sorted, ApiT.members.map(_.name).sorted + " == " + FooApi.members.map(_.name).sorted) + assert(ApiT.companion.isDefined, "test.templates.Api.T should have a pseudo-companion object") + testDiagram(ApiT, ApiT.inheritanceDiagram, 2, 1) + } +} \ No newline at end of file -- cgit v1.2.3 From 0018f9b3649f14d16debc966e7da4e54a9a0a4c3 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Wed, 18 Jul 2012 20:46:03 +0200 Subject: Scaladoc: Typers change as requested by @adriaanm on pull request #925 --- src/compiler/scala/tools/nsc/typechecker/Typers.scala | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/typechecker/Typers.scala b/src/compiler/scala/tools/nsc/typechecker/Typers.scala index 2d277603ee..a2ada0bf24 100644 --- a/src/compiler/scala/tools/nsc/typechecker/Typers.scala +++ b/src/compiler/scala/tools/nsc/typechecker/Typers.scala @@ -1972,9 +1972,7 @@ trait Typers extends Modes with Adaptations with Tags { case SilentResultValue(tpt) => val alias = enclClass.newAliasType(name.toTypeName, useCase.pos) val tparams = cloneSymbolsAtOwner(tpt.tpe.typeSymbol.typeParams, alias) - /* Unless we treat no-tparams usecases differently they blow up in typeFun - * def typeFun = PolyType(tparams, tpe) // <- which asserts (!tparams.isEmpty) */ - val newInfo = if (tparams.isEmpty) tpt.tpe else typeFun(tparams, appliedType(tpt.tpe, tparams map (_.tpe))) + val newInfo = genPolyType(tparams, appliedType(tpt.tpe, tparams map (_.tpe))) alias setInfo newInfo context.scope.enter(alias) case _ => -- cgit v1.2.3 From 0d367d4794e45ef021d9dfc7eeca186ba9fb632a Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Wed, 18 Jul 2012 20:28:06 +0200 Subject: Scaladoc: Groups Group class members based on their semantic relationship. To do this: - @group on members, only need to do it for the non-overridden members - -groups flag passes to scaladoc, groups="on" in ant - @groupdesc Group Group Description to add descriptions - @groupname Group New name for group - @groupprio Group (lower is better) See test/scaladoc/run/groups.scala for a top-to-bottom example --- build.xml | 37 +++--- src/compiler/scala/tools/ant/Scaladoc.scala | 8 ++ src/compiler/scala/tools/nsc/ast/DocComments.scala | 23 ++-- src/compiler/scala/tools/nsc/doc/Settings.scala | 7 +- .../scala/tools/nsc/doc/html/page/Template.scala | 42 ++++++- .../tools/nsc/doc/html/resource/lib/template.css | 25 ++++ .../tools/nsc/doc/html/resource/lib/template.js | 135 ++++++++++++++++----- .../scala/tools/nsc/doc/model/Entity.scala | 13 +- .../scala/tools/nsc/doc/model/ModelFactory.scala | 21 ++++ .../scala/tools/nsc/doc/model/comment/Body.scala | 2 +- .../tools/nsc/doc/model/comment/Comment.scala | 12 ++ .../nsc/doc/model/comment/CommentFactory.scala | 43 ++++++- src/compiler/scala/tools/nsc/util/DocStrings.scala | 6 + .../scala/tools/partest/ScaladocModelTest.scala | 9 +- test/scaladoc/run/groups.check | 1 + test/scaladoc/run/groups.scala | 119 ++++++++++++++++++ 16 files changed, 436 insertions(+), 67 deletions(-) create mode 100644 test/scaladoc/run/groups.check create mode 100644 test/scaladoc/run/groups.scala (limited to 'src') diff --git a/build.xml b/build.xml index b5db4ab4f4..304df1caf1 100644 --- a/build.xml +++ b/build.xml @@ -2044,7 +2044,7 @@ BOOTSTRAPPING BUILD (STRAP) LIBRARIES (Forkjoin, FJBG, ASM) ============================================================================ --> - + @@ -2112,9 +2112,10 @@ DOCUMENTATION classpathref="pack.classpath" addparams="${scalac.args.all}" docRootContent="${src.dir}/library/rootdoc.txt" - implicits="on" - diagrams="on" - rawOutput="${scaladoc.raw.output}" + implicits="on" + diagrams="on" + groups="on" + rawOutput="${scaladoc.raw.output}" noPrefixes="${scaladoc.no.prefixes}"> @@ -2199,8 +2200,9 @@ DOCUMENTATION srcdir="${src.dir}/compiler" docRootContent="${src.dir}/compiler/rootdoc.txt" addparams="${scalac.args.all}" - implicits="on" - diagrams="on" + implicits="on" + diagrams="on" + groups="on" rawOutput="${scaladoc.raw.output}" noPrefixes="${scaladoc.no.prefixes}"> @@ -2224,8 +2226,9 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/jline/src/main/java" addparams="${scalac.args.all}" - implicits="on" - diagrams="on" + implicits="on" + diagrams="on" + groups="on" rawOutput="${scaladoc.raw.output}" noPrefixes="${scaladoc.no.prefixes}"> @@ -2252,7 +2255,8 @@ DOCUMENTATION srcdir="${src.dir}/scalap" addparams="${scalac.args.all}" implicits="on" - diagrams="on" + diagrams="on" + groups="on" rawOutput="${scaladoc.raw.output}" noPrefixes="${scaladoc.no.prefixes}"> @@ -2276,8 +2280,9 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/partest" addparams="${scalac.args.all}" - implicits="on" - diagrams="on" + implicits="on" + diagrams="on" + groups="on" rawOutput="${scaladoc.raw.output}" noPrefixes="${scaladoc.no.prefixes}"> @@ -2301,8 +2306,9 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/continuations/plugin" addparams="${scalac.args.all}" - implicits="on" - diagrams="on" + implicits="on" + diagrams="on" + groups="on" rawOutput="${scaladoc.raw.output}" noPrefixes="${scaladoc.no.prefixes}"> @@ -2326,8 +2332,9 @@ DOCUMENTATION classpathref="pack.classpath" srcdir="${src.dir}/actors-migration" addparams="${scalac.args.all}" - implicits="on" - diagrams="on" + implicits="on" + diagrams="on" + groups="on" rawOutput="${scaladoc.raw.output}" noPrefixes="${scaladoc.no.prefixes}"> diff --git a/src/compiler/scala/tools/ant/Scaladoc.scala b/src/compiler/scala/tools/ant/Scaladoc.scala index 03cb770474..6201501a71 100644 --- a/src/compiler/scala/tools/ant/Scaladoc.scala +++ b/src/compiler/scala/tools/ant/Scaladoc.scala @@ -156,6 +156,9 @@ class Scaladoc extends ScalaMatchingTask { /** Instruct the scaladoc not to generate prefixes */ private var docNoPrefixes: Boolean = false + /** Instruct the scaladoc tool to group similar functions together */ + private var docGroups: Boolean = false + /*============================================================================*\ ** Properties setters ** \*============================================================================*/ @@ -435,6 +438,10 @@ class Scaladoc extends ScalaMatchingTask { def setNoPrefixes(input: String) = docNoPrefixes = Flag.getBooleanValue(input, "noPrefixes") + /** Instruct the scaladoc tool to group similar functions together */ + def setGroups(input: String) = + docGroups = Flag.getBooleanValue(input, "groups") + /*============================================================================*\ ** Properties getters ** \*============================================================================*/ @@ -634,6 +641,7 @@ class Scaladoc extends ScalaMatchingTask { docSettings.docDiagramsDebug.value = docDiagramsDebug docSettings.docRawOutput.value = docRawOutput docSettings.docNoPrefixes.value = docNoPrefixes + docSettings.docGroups.value = docGroups if(!docDiagramsDotPath.isEmpty) docSettings.docDiagramsDotPath.value = docDiagramsDotPath.get if (!docgenerator.isEmpty) docSettings.docgenerator.value = docgenerator.get diff --git a/src/compiler/scala/tools/nsc/ast/DocComments.scala b/src/compiler/scala/tools/nsc/ast/DocComments.scala index 19af01bda8..c2530bd5c7 100755 --- a/src/compiler/scala/tools/nsc/ast/DocComments.scala +++ b/src/compiler/scala/tools/nsc/ast/DocComments.scala @@ -171,15 +171,15 @@ trait DocComments { self: Global => * 3. If there is no @return section in `dst` but there is one in `src`, copy it. */ def merge(src: String, dst: String, sym: Symbol, copyFirstPara: Boolean = false): String = { - val srcSections = tagIndex(src) - val dstSections = tagIndex(dst) - val srcParams = paramDocs(src, "@param", srcSections) - val dstParams = paramDocs(dst, "@param", dstSections) - val srcTParams = paramDocs(src, "@tparam", srcSections) - val dstTParams = paramDocs(dst, "@tparam", dstSections) - val out = new StringBuilder - var copied = 0 - var tocopy = startTag(dst, dstSections dropWhile (!isMovable(dst, _))) + val srcSections = tagIndex(src) + val dstSections = tagIndex(dst) + val srcParams = paramDocs(src, "@param", srcSections) + val dstParams = paramDocs(dst, "@param", dstSections) + val srcTParams = paramDocs(src, "@tparam", srcSections) + val dstTParams = paramDocs(dst, "@tparam", dstSections) + val out = new StringBuilder + var copied = 0 + var tocopy = startTag(dst, dstSections dropWhile (!isMovable(dst, _))) if (copyFirstPara) { val eop = // end of comment body (first para), which is delimited by blank line, or tag, or end of comment @@ -209,6 +209,11 @@ trait DocComments { self: Global => for (tparam <- sym.typeParams) mergeSection(srcTParams get tparam.name.toString, dstTParams get tparam.name.toString) mergeSection(returnDoc(src, srcSections), returnDoc(dst, dstSections)) + if (sym.name.toString == "isEmpty") { + println(groupDoc(src, srcSections)) + println(groupDoc(dst, dstSections)) + } + mergeSection(groupDoc(src, srcSections), groupDoc(dst, dstSections)) if (out.length == 0) dst else { diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala index 7662381186..ad178b8158 100644 --- a/src/compiler/scala/tools/nsc/doc/Settings.scala +++ b/src/compiler/scala/tools/nsc/doc/Settings.scala @@ -188,6 +188,11 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) "Expand all type aliases and abstract types into full template pages. (locally this can be done with the @template annotation)" ) + val docGroups = BooleanSetting ( + "-groups", + "Group similar functions together (based on the @group annotation)" + ) + // Somewhere slightly before r18708 scaladoc stopped building unless the // self-type check was suppressed. I hijacked the slotted-for-removal-anyway // suppress-vt-warnings option and renamed it for this purpose. @@ -201,7 +206,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) docImplicits, docImplicitsDebug, docImplicitsShowAll, docDiagramsMaxNormalClasses, docDiagramsMaxImplicitClasses, docNoPrefixes, docNoLinkWarnings, docRawOutput, docSkipPackages, - docExpandAllTypes + docExpandAllTypes, docGroups ) val isScaladocSpecific: String => Boolean = scaladocSpecific map (_.name) 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 487ef447e9..422ea5ef1c 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -110,10 +110,26 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp
    - { if (tpl.linearizationTemplates.isEmpty && tpl.conversions.isEmpty) NodeSeq.Empty else + { if (tpl.linearizationTemplates.isEmpty && tpl.conversions.isEmpty && (!universe.settings.docGroups.value || (tpl.members.map(_.group).distinct.length == 1))) + NodeSeq.Empty + else
    Ordering -
    1. Alphabetic
    2. By inheritance
    +
      + { + if (!universe.settings.docGroups.value || (tpl.members.map(_.group).distinct.length == 1)) + NodeSeq.Empty + else +
    1. Grouped
      2. + } +
    2. Alphabetic
      3. + { + if (tpl.linearizationTemplates.isEmpty && tpl.conversions.isEmpty) + NodeSeq.Empty + else +
    3. By inheritance
      4. + } +
    } { if (tpl.linearizationTemplates.isEmpty && tpl.conversions.isEmpty) NodeSeq.Empty else @@ -223,6 +239,25 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp }
    +
    + { + val allGroups = tpl.members.map(_.group).distinct + val orderedGroups = allGroups.map(group => (tpl.groupPriority(group), group)).sorted.map(_._2) + // linearization + NodeSeq fromSeq (for (group <- orderedGroups) yield +
    +

    { tpl.groupName(group) }

    + { + tpl.groupDescription(group) match { + case Some(body) =>
    { bodyToHtml(body) }
    + case _ => NodeSeq.Empty + } + } +
    + ) + } +
    +
    @@ -242,7 +277,8 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp val memberComment = memberToCommentHtml(mbr, inTpl, false)
  3. + fullComment={ if(memberComment.filter(_.label=="div").isEmpty) "no" else "yes" } + group={ mbr.group }> { signature(mbr, false) } { memberComment } diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css b/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css index 1bee55313b..6fb7953724 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css @@ -253,6 +253,17 @@ dl.attributes > dd { color: white; } +#groupedMembers > div.group > h3 { + background: #dadada url("typebg.gif") repeat-x bottom left; /* green */ + height: 17px; + font-size: 12pt; +} + +#groupedMembers > div.group > h3 * { + color: white; +} + + /* Member cells */ div.members > ol { @@ -516,6 +527,20 @@ div.members > ol > li:last-child { /* Comments structured layout */ +.group > div.comment { + padding-top: 5px; + padding-bottom: 5px; + padding-right: 5px; + padding-left: 5px; + border: 1px solid #ddd; + background-color: #eeeee; + margin-top:5px; + margin-bottom:5px; + margin-right:5px; + margin-left:5px; + display: block; +} + p.comment { display: block; margin-left: 14.7em; diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.js b/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.js index c418c3280b..afd0293fe1 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.js +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.js @@ -43,20 +43,20 @@ $(document).ready(function(){ case 33: //page up input.val(""); - filter(false); + filter(false); break; case 34: //page down input.val(""); - filter(false); - break; + filter(false); + break; - default: + default: window.scrollTo(0, $("#mbrsel").offset().top); - filter(true); + filter(true); break; - } + } }); input.focus(function(event) { input.select(); @@ -70,7 +70,7 @@ $(document).ready(function(){ if (event.keyCode == 9) { // tab $("#index-input", window.parent.document).focus(); input.attr("value", ""); - return false; + return false; } }); @@ -135,18 +135,21 @@ $(document).ready(function(){ }); $("#order > ol > li.alpha").click(function() { if ($(this).hasClass("out")) { - $(this).removeClass("out").addClass("in"); - $("#order > ol > li.inherit").removeClass("in").addClass("out"); orderAlpha(); }; }) $("#order > ol > li.inherit").click(function() { if ($(this).hasClass("out")) { - $(this).removeClass("out").addClass("in"); - $("#order > ol > li.alpha").removeClass("in").addClass("out"); orderInherit(); }; }); + $("#order > ol > li.group").click(function() { + if ($(this).hasClass("out")) { + orderGroup(); + }; + }); + $("#groupedMembers").hide(); + initInherit(); // Create tooltips @@ -202,9 +205,14 @@ $(document).ready(function(){ // Set parent window title windowTitle(); + + if ($("#order > ol > li.group").length == 1) { orderGroup(); }; }); function orderAlpha() { + $("#order > ol > li.alpha").removeClass("out").addClass("in"); + $("#order > ol > li.inherit").removeClass("in").addClass("out"); + $("#order > ol > li.group").removeClass("in").addClass("out"); $("#template > div.parent").hide(); $("#template > div.conversion").hide(); $("#mbrsel > div[id=ancestors]").show(); @@ -212,12 +220,25 @@ function orderAlpha() { }; function orderInherit() { + $("#order > ol > li.inherit").removeClass("out").addClass("in"); + $("#order > ol > li.alpha").removeClass("in").addClass("out"); + $("#order > ol > li.group").removeClass("in").addClass("out"); $("#template > div.parent").show(); $("#template > div.conversion").show(); $("#mbrsel > div[id=ancestors]").hide(); filter(); }; +function orderGroup() { + $("#order > ol > li.group").removeClass("out").addClass("in"); + $("#order > ol > li.alpha").removeClass("in").addClass("out"); + $("#order > ol > li.inherit").removeClass("in").addClass("out"); + $("#template > div.parent").hide(); + $("#template > div.conversion").hide(); + $("#mbrsel > div[id=ancestors]").show(); + filter(); +}; + /** Prepares the DOM for inheritance-based display. To do so it will: * - hide all statically-generated parents headings; * - copy all members from the value and type members lists (flat members) to corresponding lists nested below the @@ -225,44 +246,74 @@ function orderInherit() { * - initialises a control variable used by the filter method to control whether filtering happens on flat members * or on inheritance-grouped members. */ function initInherit() { - // parents is a map from fully-qualified names to the DOM node of parent headings. - var parents = new Object(); + // inheritParents is a map from fully-qualified names to the DOM node of parent headings. + var inheritParents = new Object(); + var groupParents = new Object(); $("#inheritedMembers > div.parent").each(function(){ - parents[$(this).attr("name")] = $(this); + inheritParents[$(this).attr("name")] = $(this); }); $("#inheritedMembers > div.conversion").each(function(){ - parents[$(this).attr("name")] = $(this); + inheritParents[$(this).attr("name")] = $(this); + }); + $("#groupedMembers > div.group").each(function(){ + groupParents[$(this).attr("name")] = $(this); }); + $("#types > ol > li").each(function(){ var mbr = $(this); this.mbrText = mbr.find("> .fullcomment .cmt").text(); var qualName = mbr.attr("name"); var owner = qualName.slice(0, qualName.indexOf("#")); var name = qualName.slice(qualName.indexOf("#") + 1); - var parent = parents[owner]; - if (parent != undefined) { - var types = $("> .types > ol", parent); + var inheritParent = inheritParents[owner]; + if (inheritParent != undefined) { + var types = $("> .types > ol", inheritParent); + if (types.length == 0) { + inheritParent.append("

    Type Members

      "); + types = $("> .types > ol", inheritParent); + } + var clone = mbr.clone(); + clone[0].mbrText = this.mbrText; + types.append(clone); + } + var group = mbr.attr("group") + var groupParent = groupParents[group]; + if (groupParent != undefined) { + var types = $("> .types > ol", groupParent); if (types.length == 0) { - parent.append("

      Type Members

        "); - types = $("> .types > ol", parent); + groupParent.append("
          "); + types = $("> .types > ol", groupParent); } var clone = mbr.clone(); clone[0].mbrText = this.mbrText; types.append(clone); } }); + $("#values > ol > li").each(function(){ var mbr = $(this); this.mbrText = mbr.find("> .fullcomment .cmt").text(); var qualName = mbr.attr("name"); var owner = qualName.slice(0, qualName.indexOf("#")); var name = qualName.slice(qualName.indexOf("#") + 1); - var parent = parents[owner]; - if (parent != undefined) { - var values = $("> .values > ol", parent); + var inheritParent = inheritParents[owner]; + if (inheritParent != undefined) { + var values = $("> .values > ol", inheritParent); if (values.length == 0) { - parent.append("

          Value Members

            "); - values = $("> .values > ol", parent); + inheritParent.append("

            Value Members

              "); + values = $("> .values > ol", inheritParent); + } + var clone = mbr.clone(); + clone[0].mbrText = this.mbrText; + values.append(clone); + } + var group = mbr.attr("group") + var groupParent = groupParents[group]; + if (groupParent != undefined) { + var values = $("> .values > ol", groupParent); + if (values.length == 0) { + groupParent.append("
                "); + values = $("> .values > ol", groupParent); } var clone = mbr.clone(); clone[0].mbrText = this.mbrText; @@ -275,6 +326,9 @@ function initInherit() { $("#inheritedMembers > div.conversion").each(function() { if ($("> div.members", this).length == 0) { $(this).remove(); }; }); + $("#groupedMembers > div.group").each(function() { + if ($("> div.members", this).length == 0) { $(this).remove(); }; + }); }; /* filter used to take boolean scrollToMember */ @@ -284,26 +338,43 @@ function filter() { var queryRegExp = new RegExp(query, "i"); var privateMembersHidden = $("#visbl > ol > li.public").hasClass("in"); var orderingAlphabetic = $("#order > ol > li.alpha").hasClass("in"); - var hiddenSuperclassElementsLinearization = orderingAlphabetic ? $("#linearization > li.out") : $("#linearization > li:gt(0)"); + var orderingInheritance = $("#order > ol > li.inherit").hasClass("in"); + var orderingGroups = $("#order > ol > li.group").hasClass("in"); + var hiddenSuperclassElementsLinearization = orderingInheritance ? $("#linearization > li:gt(0)") : $("#linearization > li.out"); var hiddenSuperclassesLinearization = hiddenSuperclassElementsLinearization.map(function() { return $(this).attr("name"); }).get(); - var hiddenSuperclassElementsImplicits = orderingAlphabetic ? $("#implicits > li.out") : $("#implicits > li"); + var hiddenSuperclassElementsImplicits = orderingInheritance ? $("#implicits > li") : $("#implicits > li.out"); var hiddenSuperclassesImplicits = hiddenSuperclassElementsImplicits.map(function() { return $(this).attr("name"); }).get(); var hideInheritedMembers; - if(orderingAlphabetic) { + if (orderingAlphabetic) { + $("#allMembers").show(); $("#inheritedMembers").hide(); + $("#groupedMembers").hide(); hideInheritedMembers = true; $("#allMembers > .members").each(filterFunc); - } - else { - $("#inheritedMembers").show(); + } else if (orderingGroups) { + $("#groupedMembers").show(); + $("#inheritedMembers").hide(); + $("#allMembers").hide(); hideInheritedMembers = true; - $("#allMembers > .members").each(filterFunc); + $("#groupedMembers > .group > .members").each(filterFunc); + $("#groupedMembers > div.group").each(function() { + $(this).show(); + if ($("> div.members", this).not(":hidden").length == 0) { + $(this).hide(); + } else { + $(this).show(); + } + }); + } else if (orderingInheritance) { + $("#inheritedMembers").show(); + $("#groupedMembers").hide(); + $("#allMembers").hide(); hideInheritedMembers = false; $("#inheritedMembers > .parent > .members").each(filterFunc); $("#inheritedMembers > .conversion > .members").each(filterFunc); diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala index 0836d7e4da..16ade0787e 100644 --- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala +++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala @@ -116,6 +116,9 @@ trait MemberEntity extends Entity { /** The comment attached to this member, if any. */ def comment: Option[Comment] + /** The group this member is from */ + def group: String + /** The template of which this entity is a member. */ def inTemplate: DocTemplateEntity @@ -218,7 +221,6 @@ trait HigherKinded { /** The type parameters of this entity. */ def typeParams: List[TypeParam] - } @@ -328,6 +330,15 @@ trait DocTemplateEntity extends MemberTemplateEntity { /** If this template contains other templates, such as classes and traits, they will be shown in this diagram */ def contentDiagram: Option[Diagram] + + /** Returns the group description taken either from this template or its linearizationTypes */ + def groupDescription(group: String): Option[Body] + + /** Returns the group description taken either from this template or its linearizationTypes */ + def groupPriority(group: String): Int + + /** Returns the group description taken either from this template or its linearizationTypes */ + def groupName(group: String): String } /** A trait template. */ diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 0ba32fceaa..eba3e080ef 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -121,6 +121,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { } if (inTpl != null) thisFactory.comment(sym, thisTpl, inTpl) else None } + def group = if (comment.isDefined) comment.get.group.getOrElse("No Group") else "No Group" override def inTemplate = inTpl override def toRoot: List[MemberImpl] = this :: inTpl.toRoot def inDefinitionTemplates = this match { @@ -479,9 +480,29 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { case None => List() } else List.empty + // These are generated on-demand, make sure you don't call them more than once def inheritanceDiagram = makeInheritanceDiagram(this) def contentDiagram = makeContentDiagram(this) + + def groupSearch[T](extractor: Comment => T, default: T): T = { + // query this template + if (comment.isDefined) { + val entity = extractor(comment.get) + if (entity != default) return entity + } + // query linearization + if (!sym.isAliasType && !sym.isAbstractType) + for (tpl <- linearizationTemplates.collect{ case dtpl: DocTemplateImpl if dtpl!=this => dtpl}) { + val entity = tpl.groupSearch(extractor, default) + if (entity != default) return entity + } + default + } + + def groupDescription(group: String): Option[Body] = groupSearch(_.groupDesc.get(group), None) + def groupPriority(group: String): Int = groupSearch(_.groupPrio.get(group) match { case Some(prio) => prio; case _ => 0 }, 0) + def groupName(group: String): String = groupSearch(_.groupNames.get(group) match { case Some(name) => name; case _ => group }, group) } abstract class PackageImpl(sym: Symbol, inTpl: PackageImpl) extends DocTemplateImpl(sym, inTpl) with Package { diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala b/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala index 3ab8fc7805..3f0024cb68 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala @@ -71,7 +71,7 @@ final case class Monospace(text: Inline) extends Inline final case class Text(text: String) extends Inline abstract class EntityLink(val title: Inline) extends Inline { def link: LinkTo } object EntityLink { - def apply(title: Inline, linkTo: LinkTo) = new EntityLink(title) { def link: LinkTo = linkTo} + def apply(title: Inline, linkTo: LinkTo) = new EntityLink(title) { def link: LinkTo = linkTo } def unapply(el: EntityLink): Option[(Inline, LinkTo)] = Some((el.title, el.link)) } final case class HtmlTag(data: String) extends Inline { diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/Comment.scala b/src/compiler/scala/tools/nsc/doc/model/comment/Comment.scala index 7b70683db5..c8f4c2f285 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/Comment.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/Comment.scala @@ -114,6 +114,18 @@ abstract class Comment { /** A set of diagram directives for the content diagram */ def contentDiagram: List[String] + /** The group this member is part of */ + def group: Option[String] + + /** Member group descriptions */ + def groupDesc: Map[String,Body] + + /** Member group names (overriding the short tag) */ + def groupNames: Map[String,String] + + /** Member group priorities */ + def groupPrio: Map[String,Int] + override def toString = body.toString + "\n" + (authors map ("@author " + _.toString)).mkString("\n") + diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala index a57ccd36c2..ac737b6ee3 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala @@ -114,7 +114,11 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory with Member constructor0: Option[Body] = None, source0: Option[String] = None, inheritDiagram0: List[String] = List.empty, - contentDiagram0: List[String] = List.empty + contentDiagram0: List[String] = List.empty, + group0: Option[Body] = None, + groupDesc0: Map[String,Body] = Map.empty, + groupNames0: Map[String,Body] = Map.empty, + groupPrio0: Map[String,Body] = Map.empty ) : Comment = new Comment{ val body = if(body0 isDefined) body0.get else Body(Seq.empty) val authors = authors0 @@ -133,6 +137,35 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory with Member val source = source0 val inheritDiagram = inheritDiagram0 val contentDiagram = contentDiagram0 + val groupDesc = groupDesc0 + val group = + group0 match { + case Some(Body(List(Paragraph(Chain(List(Summary(Text(groupId)))))))) => Some(groupId.toString.trim) + case _ => None + } + val groupPrio = groupPrio0 flatMap { + case (group, body) => + try { + body match { + case Body(List(Paragraph(Chain(List(Summary(Text(prio))))))) => List(group -> prio.toInt) + case _ => List() + } + } catch { + case _: java.lang.NumberFormatException => List() + } + } + val groupNames = groupNames0 flatMap { + case (group, body) => + try { + body match { + case Body(List(Paragraph(Chain(List(Summary(Text(name))))))) if (!name.trim.contains("\n")) => List(group -> (name.trim)) + case _ => List() + } + } catch { + case _: java.lang.NumberFormatException => List() + } + } + } protected val endOfText = '\u0003' @@ -202,7 +235,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory with Member /** A Scaladoc tag linked to a symbol. Returns the name of the tag, the name * of the symbol, and the rest of the line. */ protected val SymbolTag = - new Regex("""\s*@(param|tparam|throws)\s+(\S*)\s*(.*)""") + new Regex("""\s*@(param|tparam|throws|groupdesc|groupname|groupprio)\s+(\S*)\s*(.*)""") /** The start of a scaladoc code block */ protected val CodeBlockStart = @@ -403,7 +436,11 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory with Member constructor0 = oneTag(SimpleTagKey("constructor")), source0 = Some(clean(src).mkString("\n")), inheritDiagram0 = inheritDiagramText, - contentDiagram0 = contentDiagramText + contentDiagram0 = contentDiagramText, + group0 = oneTag(SimpleTagKey("group")), + groupDesc0 = allSymsOneTag(SimpleTagKey("groupdesc")), + groupNames0 = allSymsOneTag(SimpleTagKey("groupname")), + groupPrio0 = allSymsOneTag(SimpleTagKey("groupprio")) ) for ((key, _) <- bodyTags) diff --git a/src/compiler/scala/tools/nsc/util/DocStrings.scala b/src/compiler/scala/tools/nsc/util/DocStrings.scala index f4ce6d6ef1..c88414c423 100755 --- a/src/compiler/scala/tools/nsc/util/DocStrings.scala +++ b/src/compiler/scala/tools/nsc/util/DocStrings.scala @@ -143,6 +143,12 @@ object DocStrings { } } + /** Optionally start and end index of return section in `str`, or `None` + * if `str` does not have a @group. */ + def groupDoc(str: String, sections: List[(Int, Int)]): Option[(Int, Int)] = + sections find (startsWithTag(str, _, "@group")) + + /** Optionally start and end index of return section in `str`, or `None` * if `str` does not have a @return. */ diff --git a/src/partest/scala/tools/partest/ScaladocModelTest.scala b/src/partest/scala/tools/partest/ScaladocModelTest.scala index adf7abe11c..ffc5e74cc0 100644 --- a/src/partest/scala/tools/partest/ScaladocModelTest.scala +++ b/src/partest/scala/tools/partest/ScaladocModelTest.scala @@ -169,14 +169,19 @@ abstract class ScaladocModelTest extends DirectTest { }).mkString(", ") + "]") } - def extractCommentText(c: Comment) = { + def extractCommentText(c: Any) = { def extractText(body: Any): String = body match { case s: String => s case s: Seq[_] => s.toList.map(extractText(_)).mkString case p: Product => p.productIterator.toList.map(extractText(_)).mkString case _ => "" } - extractText(c.body) + c match { + case c: Comment => + extractText(c.body) + case b: Body => + extractText(b) + } } def countLinks(c: Comment, p: EntityLink => Boolean) = { diff --git a/test/scaladoc/run/groups.check b/test/scaladoc/run/groups.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/groups.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/groups.scala b/test/scaladoc/run/groups.scala new file mode 100644 index 0000000000..05324c2ec9 --- /dev/null +++ b/test/scaladoc/run/groups.scala @@ -0,0 +1,119 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def code = """ + package test.scaladoc.groups { + + /** + * The trait A + * @groupdesc A Group A is the group that contains functions starting with f + * For example: + * {{{ + * this is an example + * }}} + * @groupdesc B Group B is the group that contains functions starting with b + * @groupname B Group B has a nice new name and a high priority + * @groupprio B -10 + * @group Traits + * @note This is a note + */ + trait A { + /** foo description + * @group A */ + def foo = 1 + + /** bar description + * @group B */ + def bar = 2 + } + + /** The trait B + * @group Traits + * @groupdesc C Group C is introduced by B + */ + trait B { + /** baz descriptopn + * @group C */ + def baz = 3 + } + + /** The class C which inherits from both A and B + * @group Classes + * @groupdesc B Look ma, I'm overriding group descriptions!!! + * @groupname B And names + */ + class C extends A with B { + /** Oh noes, I lost my group -- or did I?!? */ + override def baz = 4 + } + } + """ + + // no need for special settings + def scaladocSettings = "-feature" + + 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("test")._package("scaladoc")._package("groups") + + def checkGroup(mbr: MemberEntity, grp: String) = + assert(mbr.group == grp, "Incorrect group for " + mbr.qualifiedName + ": " + mbr.group + " instead of " + grp) + + def checkGroupDesc(dtpl: DocTemplateEntity, grp: String, grpDesc: String) = { + assert(dtpl.groupDescription(grp).isDefined, + "Group description for " + grp + " not defined in " + dtpl.qualifiedName) + assert(extractCommentText(dtpl.groupDescription(grp).get).contains(grpDesc), + "Group description for " + grp + " in " + dtpl.qualifiedName + " does not contain \"" + grpDesc + "\": \"" + + extractCommentText(dtpl.groupDescription(grp).get) + "\"") + } + + def checkGroupName(dtpl: DocTemplateEntity, grp: String, grpName: String) = + // TODO: See why we need trim here, we already do trimming in the CommentFactory + assert(dtpl.groupName(grp) == grpName, + "Group name for " + grp + " in " + dtpl.qualifiedName + " does not equal \"" + grpName + "\": \"" + dtpl.groupName(grp) + "\"") + + def checkGroupPrio(dtpl: DocTemplateEntity, grp: String, grpPrio: Int) = + assert(dtpl.groupPriority(grp) == grpPrio, + "Group priority for " + grp + " in " + dtpl.qualifiedName + " does not equal " + grpPrio + ": " + dtpl.groupPriority(grp)) + + + val A = base._trait("A") + val B = base._trait("B") + val C = base._class("C") + checkGroup(A, "Traits") + checkGroup(B, "Traits") + checkGroup(C, "Classes") + checkGroup(A._method("foo"), "A") + checkGroup(A._method("bar"), "B") + checkGroup(B._method("baz"), "C") + checkGroup(C._method("foo"), "A") + checkGroup(C._method("bar"), "B") + checkGroup(C._method("baz"), "C") + + checkGroupDesc(A, "A", "Group A is the group that contains functions starting with f") + checkGroupName(A, "A", "A") + checkGroupPrio(A, "A", 0) + checkGroupDesc(A, "B", "Group B is the group that contains functions starting with b") + checkGroupName(A, "B", "Group B has a nice new name and a high priority") + checkGroupPrio(A, "B", -10) + + checkGroupDesc(B, "C", "Group C is introduced by B") + checkGroupName(B, "C", "C") + checkGroupPrio(B, "C", 0) + + checkGroupDesc(C, "A", "Group A is the group that contains functions starting with f") + checkGroupName(C, "A", "A") + checkGroupPrio(C, "A", 0) + checkGroupDesc(C, "B", "Look ma, I'm overriding group descriptions!!!") + checkGroupName(C, "B", "And names") + checkGroupPrio(C, "B", -10) + checkGroupDesc(C, "C", "Group C is introduced by B") + checkGroupName(C, "C", "C") + checkGroupPrio(C, "C", 0) + } +} \ No newline at end of file -- cgit v1.2.3 From 6539a9ddc5ecdec65ef1d874999a200cee46b2c4 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Thu, 19 Jul 2012 15:03:13 +0200 Subject: SI-5784 Scaladoc: Type templates @template and @documentable are now synomims. --- src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala | 3 ++- src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala | 2 +- test/scaladoc/resources/SI-5784.scala | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index eba3e080ef..af33911681 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -1075,6 +1075,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { // whether or not to create a page for an {abstract,alias} type def typeShouldDocument(bSym: Symbol, inTpl: DocTemplateImpl) = (settings.docExpandAllTypes.value && (bSym.sourceFile != null)) || - global.expandedDocComment(bSym, inTpl.sym).contains("@template") + { val rawComment = global.expandedDocComment(bSym, inTpl.sym) + rawComment.contains("@template") || rawComment.contains("@documentable") } } diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala index ac737b6ee3..1a11964e37 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala @@ -383,7 +383,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory with Member case None => List.empty } - val stripTags=List(inheritDiagramTag, contentDiagramTag, SimpleTagKey("template")) + val stripTags=List(inheritDiagramTag, contentDiagramTag, SimpleTagKey("template"), SimpleTagKey("documentable")) val tagsWithoutDiagram = tags.filterNot(pair => stripTags.contains(pair._1)) val bodyTags: mutable.Map[TagKey, List[Body]] = diff --git a/test/scaladoc/resources/SI-5784.scala b/test/scaladoc/resources/SI-5784.scala index 175cc3cf33..3731d4998c 100644 --- a/test/scaladoc/resources/SI-5784.scala +++ b/test/scaladoc/resources/SI-5784.scala @@ -8,7 +8,7 @@ package test.templates { /** @contentDiagram */ trait Base { - /** @template */ + /** @documentable */ type String = test.templates.String /** @template * @inheritanceDiagram */ @@ -20,7 +20,7 @@ package test.templates { /** @contentDiagram */ trait Api extends Base { - /** @template + /** @documentable * @inheritanceDiagram */ override type T <: FooApi trait FooApi extends Foo { def bar: String } -- cgit v1.2.3 From b0c7f0b257d86634bb344405273200310f8ba386 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Thu, 19 Jul 2012 16:03:53 +0200 Subject: Scaladoc: Adressed @hubertp's comment on #925 And relaxed the groups name/description/priority search algorithm to work for types. --- .../scala/tools/nsc/doc/model/ModelFactory.scala | 37 ++++++++++++---------- 1 file changed, 21 insertions(+), 16 deletions(-) (limited to 'src') diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index af33911681..00e6f3769e 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -492,11 +492,10 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { if (entity != default) return entity } // query linearization - if (!sym.isAliasType && !sym.isAbstractType) - for (tpl <- linearizationTemplates.collect{ case dtpl: DocTemplateImpl if dtpl!=this => dtpl}) { - val entity = tpl.groupSearch(extractor, default) - if (entity != default) return entity - } + for (tpl <- linearizationTemplates.collect{ case dtpl: DocTemplateImpl if dtpl!=this => dtpl}) { + val entity = tpl.groupSearch(extractor, default) + if (entity != default) return entity + } default } @@ -601,9 +600,10 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { } /* ============== MAKER METHODS ============== */ - /** This method makes it easier to work with the different kinds of symbols created by scalac + /** This method makes it easier to work with the different kinds of symbols created by scalac by stripping down the + * package object abstraction and placing members directly in the package. * - * Okay, here's the explanation of what happens. The code: + * Here's the explanation of what we do. The code: * * package foo { * object `package` { @@ -612,17 +612,22 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { * } * * will yield this Symbol structure: - * - * +---------------+ +--------------------------+ - * | package foo#1 ----(1)---> module class foo#2 | - * +---------------+ | +----------------------+ | +-------------------------+ - * | | package object foo#3 ------(1)---> module class package#4 | - * | +----------------------+ | | +---------------------+ | - * +--------------------------+ | | class package$Bar#5 | | - * | +---------------------+ | - * +-------------------------+ + * +---------+ (2) + * | | + * +---------------+ +---------- v ------- | ---+ +--------+ (2) + * | package foo#1 <---(1)---- module class foo#2 | | | | + * +---------------+ | +------------------ | -+ | +------------------- v ---+ | + * | | package object foo#3 <-----(1)---- module class package#4 | | + * | +----------------------+ | | +---------------------+ | | + * +--------------------------+ | | class package$Bar#5 | | | + * | +----------------- | -+ | | + * +------------------- | ---+ | + * | | + * +--------+ * (1) sourceModule * (2) you get out of owners with .owner + * + * and normalizeTemplate(Bar.owner) will get us the package, instead of the module class of the package object. */ def normalizeTemplate(aSym: Symbol): Symbol = aSym match { case null | rootMirror.EmptyPackage | NoSymbol => -- cgit v1.2.3