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. --- .../tools/nsc/doc/base/CommentFactoryBase.scala | 18 +++++++++- .../scala/tools/nsc/doc/html/page/Template.scala | 2 +- .../scala/tools/partest/ScaladocModelTest.scala | 8 +++-- test/scaladoc/run/t6626.check | 7 ++++ test/scaladoc/run/t6626.scala | 42 ++++++++++++++++++++++ 5 files changed, 72 insertions(+), 5 deletions(-) create mode 100644 test/scaladoc/run/t6626.check create mode 100644 test/scaladoc/run/t6626.scala 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) = { diff --git a/test/scaladoc/run/t6626.check b/test/scaladoc/run/t6626.check new file mode 100644 index 0000000000..de3a6c5c0b --- /dev/null +++ b/test/scaladoc/run/t6626.check @@ -0,0 +1,7 @@ +newSource:10: warning: Could not find any member to link for "SomeUnknownException". + /** + ^ +newSource:10: warning: Could not find any member to link for "IOException". + /** + ^ +Done. diff --git a/test/scaladoc/run/t6626.scala b/test/scaladoc/run/t6626.scala new file mode 100644 index 0000000000..6c61c605d6 --- /dev/null +++ b/test/scaladoc/run/t6626.scala @@ -0,0 +1,42 @@ +import scala.tools.nsc.doc.base._ +import scala.tools.nsc.doc.base.comment._ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + + override def code = """ + +package org.foo + +class MyException extends Exception + +class MyOtherException extends Exception + +object Foo { + /** + * Test exception linking + * + * @throws org.foo.MyException linked with a fully-qualified name + * @throws MyOtherException linked with a relative name + * @throws SomeUnknownException not linked at all (but with some text) + * @throws IOException + */ + def test(): Unit = ??? +} + """ + + 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 a = rootPackage._package("org")._package("foo")._object("Foo")._method("test") + val throws = a.comment.get.throws + val allbodies = Body(throws.values.flatMap(_.blocks).toSeq) + + val links = countLinksInBody(allbodies, _.link.isInstanceOf[LinkToTpl[_]]) + assert(links == 2, links + " == 2 (links to MyException and MyOtherException)") + } +} -- cgit v1.2.3