Add doc annotation `@shortDescription` to enable explicit synopsis

Entities with this annotation will be able to control what is shown in
the method summary on entity pages as well as the hover text on search
results.

Review: @VladUreche

2 files changed, 15 insertions, 5 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") +