From 315f58f5fb7241966e218e13c9b26aea8eede56e Mon Sep 17 00:00:00 2001 From: Antoine Gourlay Date: Tue, 4 Nov 2014 11:31:14 +0100 Subject: SI-6626 make @throws tags create links to exceptions In scaladoc, this turns exceptions in @throws tags into links (when it can find the target exception), instead of just showing the name. --- .../scala/tools/nsc/doc/base/CommentFactoryBase.scala | 18 +++++++++++++++++- .../scala/tools/nsc/doc/html/page/Template.scala | 2 +- .../scala/tools/partest/ScaladocModelTest.scala | 8 +++++--- 3 files changed, 23 insertions(+), 5 deletions(-) (limited to 'src/scaladoc') diff --git a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala index 7cd8fa8e51..d31b877262 100755 --- a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala @@ -345,12 +345,28 @@ trait CommentFactoryBase { this: MemberLookupBase => Map.empty[String, Body] ++ pairs } + def linkedExceptions: Map[String, Body] = { + val m = allSymsOneTag(SimpleTagKey("throws")) + + m.map { case (name,body) => + val link = memberLookup(pos, name, site) + val newBody = body match { + case Body(List(Paragraph(Chain(content)))) => + val descr = Text(" ") +: content + val entityLink = EntityLink(Monospace(Text(name)), link) + Body(List(Paragraph(Chain(entityLink +: descr)))) + case _ => body + } + (name, newBody) + } + } + val com = createComment ( body0 = Some(parseWikiAtSymbol(docBody.toString, pos, site)), authors0 = allTags(SimpleTagKey("author")), see0 = allTags(SimpleTagKey("see")), result0 = oneTag(SimpleTagKey("return")), - throws0 = allSymsOneTag(SimpleTagKey("throws")), + throws0 = linkedExceptions, valueParams0 = allSymsOneTag(SimpleTagKey("param")), typeParams0 = allSymsOneTag(SimpleTagKey("tparam")), version0 = oneTag(SimpleTagKey("version")), diff --git a/src/scaladoc/scala/tools/nsc/doc/html/page/Template.scala b/src/scaladoc/scala/tools/nsc/doc/html/page/Template.scala index b5a8d1ac36..f3df2b0bb4 100644 --- a/src/scaladoc/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/scaladoc/scala/tools/nsc/doc/html/page/Template.scala @@ -605,7 +605,7 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp
{ val exceptionsXml: List[NodeSeq] = for((name, body) <- comment.throws.toList.sortBy(_._1) ) yield - {Text(name) ++ bodyToHtml(body)} + {bodyToHtml(body)} exceptionsXml.reduceLeft(_ ++ Text("") ++ _) }
} diff --git a/src/scaladoc/scala/tools/partest/ScaladocModelTest.scala b/src/scaladoc/scala/tools/partest/ScaladocModelTest.scala index 70423cc7dc..fa3e8ff5cb 100644 --- a/src/scaladoc/scala/tools/partest/ScaladocModelTest.scala +++ b/src/scaladoc/scala/tools/partest/ScaladocModelTest.scala @@ -182,14 +182,16 @@ abstract class ScaladocModelTest extends DirectTest { } } - def countLinks(c: Comment, p: EntityLink => Boolean) = { - def countLinks(body: Any): Int = body match { + def countLinks(c: Comment, p: EntityLink => Boolean): Int = countLinksInBody(c.body, p) + + def countLinksInBody(body: Body, p: EntityLink => Boolean): Int = { + def countLinks(b: Any): Int = b 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) + countLinks(body) } def testDiagram(doc: DocTemplateEntity, diag: Option[Diagram], nodes: Int, edges: Int) = { -- cgit v1.2.3 From 6b9f5437e84b4bbb021dba6af58851ba54c3c0b7 Mon Sep 17 00:00:00 2001 From: Antoine Gourlay Date: Tue, 4 Nov 2014 14:28:48 +0100 Subject: SI-5730 hide constructors of sealed abstract classes in scaladoc Sealed abstract classes (like `List`) have a primary constructor, public by default. It can never be called by external code but it shows up in the scaladoc as a nice `new List()` construtor... If a class is only abstract, the constructor is still useful because people can subclass and call it. If it is only sealed (i.e. effectively final), then it is the normal constructor of a final class. But sealed *and* abstract makes documenting the constructor useless. This should remove the misleading constructors of `List`, `Double`, `Option` and others from the scaladoc. --- .../scala/tools/nsc/doc/model/ModelFactory.scala | 6 ++-- test/scaladoc/run/t5730.check | 1 + test/scaladoc/run/t5730.scala | 36 ++++++++++++++++++++++ 3 files changed, 41 insertions(+), 2 deletions(-) create mode 100644 test/scaladoc/run/t5730.check create mode 100644 test/scaladoc/run/t5730.scala (limited to 'src/scaladoc') diff --git a/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala b/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala index ef84ac42ba..7a67055ffa 100644 --- a/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala @@ -753,8 +753,10 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { }) } else if (bSym.isConstructor) - if (conversion.isDefined) - None // don't list constructors inherted by implicit conversion + if (conversion.isDefined || (bSym.enclClass.isAbstract && (bSym.enclClass.isSealed || bSym.enclClass.isFinal))) + // don't list constructors inherited by implicit conversion + // and don't list constructors of abstract sealed types (they cannot be accessed anyway) + None else Some(new NonTemplateParamMemberImpl(bSym, conversion, useCaseOf, inTpl) with Constructor { override def isConstructor = true diff --git a/test/scaladoc/run/t5730.check b/test/scaladoc/run/t5730.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/t5730.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/t5730.scala b/test/scaladoc/run/t5730.scala new file mode 100644 index 0000000000..cc4c2444b1 --- /dev/null +++ b/test/scaladoc/run/t5730.scala @@ -0,0 +1,36 @@ +import scala.tools.nsc.doc.base._ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def code = """ + package scala.test.scaladoc.T5730 + + /** + * A link: + * + * [[scala.Option$ object Option]]. + */ + sealed abstract class A + + case object B extends A + + abstract final class C + """ + + 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._ + + val p = rootPackage._package("scala")._package("test")._package("scaladoc")._package("T5730") + + val a = p._class("A") + val c = p._class("C") + + assert(a.constructors.isEmpty, s"there should be no constructors, found: ${a.constructors}") + assert(c.constructors.isEmpty, s"there should be no constructors, found: ${c.constructors}") + } +} -- cgit v1.2.3 From af49d9c61c805dd689bdeb9e508e78edd29fedd0 Mon Sep 17 00:00:00 2001 From: Antoine Gourlay Date: Sat, 15 Nov 2014 18:08:30 +0100 Subject: SI-8948 resurrect the scaladoc for Any/AnyRef/Nothing/Null. They disappeared in dc1cd96 when `scala.tools.nsc.doc.DocParser` lost its `override def forScaladoc = true`, which used to trigger whether to parse `DocDef` nodes. This was deprecated in favor of a custom global when scaladoc was modularized out (#2226), but `DocParser` didn't get it since it didn't override `forScaladoc` anymore... I added back `forScaladoc` in `DocParser` for consistency with `ScaladocGlobal`, although it doesn't do anything anymore. --- src/scaladoc/scala/tools/nsc/doc/DocParser.scala | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'src/scaladoc') diff --git a/src/scaladoc/scala/tools/nsc/doc/DocParser.scala b/src/scaladoc/scala/tools/nsc/doc/DocParser.scala index 6dc3e5a62b..f03b848af6 100644 --- a/src/scaladoc/scala/tools/nsc/doc/DocParser.scala +++ b/src/scaladoc/scala/tools/nsc/doc/DocParser.scala @@ -15,13 +15,14 @@ import DocParser.Parsed * right after parsing so it can read `DocDefs` from source code which would * otherwise cause the compiler to go haywire. */ -class DocParser(settings: nsc.Settings, reporter: Reporter) extends Global(settings, reporter) { +class DocParser(settings: nsc.Settings, reporter: Reporter) extends Global(settings, reporter) with ScaladocGlobalTrait { def this(settings: Settings) = this(settings, new ConsoleReporter(settings)) def this() = this(new Settings(Console println _)) // the usual global initialization locally { new Run() } + override def forScaladoc = true override protected def computeInternalPhases() { phasesSet += syntaxAnalyzer } -- cgit v1.2.3 From 50a9c1bc448d976b1a7dbafc38d9ac54674721af Mon Sep 17 00:00:00 2001 From: Antoine Gourlay Date: Sat, 15 Nov 2014 20:09:05 +0100 Subject: No list of subclasses for Any in scaladoc, it's useless. --- src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/scaladoc') diff --git a/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala b/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala index 7a67055ffa..7289edc137 100644 --- a/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala @@ -313,7 +313,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { /* Subclass cache */ private lazy val subClassesCache = ( - if (sym == AnyRefClass) null + if (sym == AnyRefClass || sym == AnyClass) null else mutable.ListBuffer[DocTemplateEntity]() ) def registerSubClass(sc: DocTemplateEntity): Unit = { -- cgit v1.2.3 From 89c000f70946890a1fc8c378804e1647d271c479 Mon Sep 17 00:00:00 2001 From: Dick Wall Date: Tue, 25 Nov 2014 07:07:02 -0800 Subject: SI-9006 Scaladoc: explicit companion and package links The existing navigation mechanisms have proved hard to discover for newcomers to Scaladoc. This commit adds textual links in the navigation bar to the docs of the companion (if defined) and to those of the enclosing package. --- src/scaladoc/scala/tools/nsc/doc/html/HtmlPage.scala | 20 ++++++++++++++++++++ .../scala/tools/nsc/doc/html/page/Template.scala | 4 +++- .../tools/nsc/doc/html/resource/lib/template.css | 12 ++++++++++++ 3 files changed, 35 insertions(+), 1 deletion(-) (limited to 'src/scaladoc') diff --git a/src/scaladoc/scala/tools/nsc/doc/html/HtmlPage.scala b/src/scaladoc/scala/tools/nsc/doc/html/HtmlPage.scala index 295bae5bef..3738e79ffe 100644 --- a/src/scaladoc/scala/tools/nsc/doc/html/HtmlPage.scala +++ b/src/scaladoc/scala/tools/nsc/doc/html/HtmlPage.scala @@ -228,6 +228,26 @@ abstract class HtmlPage extends Page { thisPage => + def companionAndPackage(tpl: DocTemplateEntity): Elem = + { + tpl.companion match { + case Some(companionTpl) => + val objClassTrait = + if (companionTpl.isObject) s"object ${tpl.name}" + else if (companionTpl.isTrait) s"trait ${companionTpl.name}" + else s"class ${companionTpl.name}" +
+ Related Docs: + {objClassTrait} + | {templateToHtml(tpl.inTemplate, s"package ${tpl.inTemplate.name}")} +
+ case None => +
Related Doc: + {templateToHtml(tpl.inTemplate, s"package ${tpl.inTemplate.name}")} +
+ } + } + def memberToUrl(template: Entity, isSelf: Boolean = true): String = { val (signature: Option[String], containingTemplate: TemplateEntity) = template match { case dte: DocTemplateEntity if (!isSelf) => (Some(dte.signature), dte.inTemplate) diff --git a/src/scaladoc/scala/tools/nsc/doc/html/page/Template.scala b/src/scaladoc/scala/tools/nsc/doc/html/page/Template.scala index f3df2b0bb4..eda52c5fbf 100644 --- a/src/scaladoc/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/scaladoc/scala/tools/nsc/doc/html/page/Template.scala @@ -110,7 +110,9 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp }} { owner } -

{ displayName }

{ permalink(tpl) } +

{ displayName }

{ + if (tpl.isPackage) NodeSeq.Empty else

{companionAndPackage(tpl)}

+ }{ permalink(tpl) } { signature(tpl, isSelf = true) } diff --git a/src/scaladoc/scala/tools/nsc/doc/html/resource/lib/template.css b/src/scaladoc/scala/tools/nsc/doc/html/resource/lib/template.css index 35f66cd5df..e129e6cf6a 100644 --- a/src/scaladoc/scala/tools/nsc/doc/html/resource/lib/template.css +++ b/src/scaladoc/scala/tools/nsc/doc/html/resource/lib/template.css @@ -397,6 +397,18 @@ div.members > ol > li:last-child { margin-bottom: 5px; } +#definition .morelinks { + text-align: right; + position: absolute; + top: 40px; + right: 10px; + width: 450px; +} + +#definition .morelinks a { + color: #EBEBEB; +} + #template .members li .permalink { position: absolute; top: 5px; -- cgit v1.2.3