diff options
5 files changed, 71 insertions, 6 deletions
diff --git a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala index 707d0c469f..8cd8a7ee09 100644 --- a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala @@ -47,7 +47,8 @@ trait CommentFactoryBase { this: MemberLookupBase => groupDesc0: Map[String,Body] = Map.empty, groupNames0: Map[String,Body] = Map.empty, groupPrio0: Map[String,Body] = Map.empty, - hideImplicitConversions0: List[Body] = List.empty + hideImplicitConversions0: List[Body] = List.empty, + shortDescription0: List[Body] = List.empty ): Comment = new Comment { val body = body0 getOrElse Body(Seq.empty) val authors = authors0 @@ -90,9 +91,13 @@ trait CommentFactoryBase { this: MemberLookupBase => } } + override val shortDescription: Option[Text] = shortDescription0.lastOption collect { + case Body(List(Paragraph(Chain(List(Summary(Text(e))))))) if !e.trim.contains("\n") => Text(e) + } + override val hideImplicitConversions: List[String] = hideImplicitConversions0 flatMap { - case Body(List(Paragraph(Chain(List(Summary(Text(e))))))) if (!e.trim.contains("\n")) => List(e) + case Body(List(Paragraph(Chain(List(Summary(Text(e))))))) if !e.trim.contains("\n") => List(e) case _ => List() } } @@ -397,7 +402,8 @@ trait CommentFactoryBase { this: MemberLookupBase => groupDesc0 = allSymsOneTag(SimpleTagKey("groupdesc")), groupNames0 = allSymsOneTag(SimpleTagKey("groupname")), groupPrio0 = allSymsOneTag(SimpleTagKey("groupprio")), - hideImplicitConversions0 = allTags(SimpleTagKey("hideImplicitConversion")) + hideImplicitConversions0 = allTags(SimpleTagKey("hideImplicitConversion")), + shortDescription0 = allTags(SimpleTagKey("shortDescription")) ) for ((key, _) <- bodyTags) diff --git a/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala b/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala index 81f8c3ec06..eeb861e246 100644 --- a/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala @@ -47,9 +47,10 @@ abstract class Comment { Chain(List(inline) ++ stack.reverse) } - /** A shorter version of the body. Usually, this is the first sentence of the body. */ + /** A shorter version of the body. Either from `@shortDescription` or the + * first sentence of the body. */ def short: Inline = { - body.summary match { + shortDescription orElse body.summary match { case Some(s) => closeHtmlTags(s) case _ => @@ -126,6 +127,9 @@ abstract class Comment { /** A list of implicit conversions to hide */ def hideImplicitConversions: List[String] + /** A short description used in the entity-view and search results */ + def shortDescription: Option[Text] + override def toString = body.toString + "\n" + (authors map ("@author " + _.toString)).mkString("\n") + diff --git a/test/scaladoc/run/SI-9620.scala b/test/scaladoc/run/SI-9620.scala index 96260aad9a..cac34d1c18 100644 --- a/test/scaladoc/run/SI-9620.scala +++ b/test/scaladoc/run/SI-9620.scala @@ -21,7 +21,6 @@ object Test extends ScaladocModelTest { } """ - // no need for special settings def scaladocSettings = "-implicits" def testModel(rootPackage: Package) = { diff --git a/test/scaladoc/run/shortDescription-annotation.check b/test/scaladoc/run/shortDescription-annotation.check new file mode 100644 index 0000000000..619c56180b --- /dev/null +++ b/test/scaladoc/run/shortDescription-annotation.check @@ -0,0 +1 @@ +Done. diff --git a/test/scaladoc/run/shortDescription-annotation.scala b/test/scaladoc/run/shortDescription-annotation.scala new file mode 100644 index 0000000000..0e2950f4f9 --- /dev/null +++ b/test/scaladoc/run/shortDescription-annotation.scala @@ -0,0 +1,55 @@ +import scala.tools.nsc.doc.model._ +import scala.tools.partest.ScaladocModelTest + +object Test extends ScaladocModelTest { + override def code = """ + package a + + /** This comment should not appear + * @shortDescription This one should appear + */ + class Foo { + /** This comment should appear */ + def foo: Int = 1 + + /** This comment should not appear + * @shortDescription This comment should appear + */ + def goo: Int = 2 + } + """ + + // no need for special settings + def scaladocSettings = "" + + def testModel(rootPackage: Package) = { + import scala.tools.nsc.doc.base.comment._ + import access._ + + def inlineToStr(inl: Inline): String = inl match { + case Chain(items) => items flatMap (inlineToStr(_)) mkString "" + case Italic(in) => inlineToStr(in) + case Bold(in) => inlineToStr(in) + case Underline(in) => inlineToStr(in) + case Monospace(in) => inlineToStr(in) + case Text(text) => text + case Summary(in) => inlineToStr(in) + case EntityLink(Text(text), _) => text + case _ => inl.toString + } + + val foo = rootPackage._package("a")._class("Foo") + + // Assert that the class has the correct short description + val classDesc = inlineToStr(foo.comment.get.short) + assert(classDesc == "This one should appear", classDesc) + + // Assert that the `foo` method has the correct short description + val fooDesc = inlineToStr(foo._method("foo").comment.get.short) + assert(fooDesc == "This comment should appear", fooDesc) + + // Assert that the `goo` method has the correct short description + val gooDesc = inlineToStr(foo._method("goo").comment.get.short) + assert(gooDesc == "This comment should appear", gooDesc) + } +} |