Merge pull request scala#5728 from Philippus/issue/html-tag-in-hover

inlineToStr is not exhaustive and does not remove html tags inside HtmlTag [ci: last-only]

src/scaladoc/scala/tools/nsc/doc/html/Page.scala

@@ -7,7 +7,7 @@ package scala
 package tools.nsc.doc.html
 
 import scala.tools.nsc.doc.model._
-import scala.tools.nsc.doc.base.comment
+import scala.tools.nsc.doc.base.comment._
 import java.io.{FileOutputStream, File}
 import scala.reflect.NameTransformer
 import java.nio.channels.Channels
@@ -106,16 +106,21 @@ abstract class Page {
     case dtpl: DocTemplateEntity => dtpl.companion.isDefined
     case _ => false
   }
+}
 
-  protected def inlineToStr(inl: comment.Inline): String = inl match {
-    case comment.Chain(items) => items flatMap (inlineToStr(_)) mkString ""
-    case comment.Italic(in) => inlineToStr(in)
-    case comment.Bold(in) => inlineToStr(in)
-    case comment.Underline(in) => inlineToStr(in)
-    case comment.Monospace(in) => inlineToStr(in)
-    case comment.Text(text) => text
-    case comment.Summary(in) => inlineToStr(in)
-    case comment.EntityLink(comment.Text(text), _) => text
-    case _ => inl.toString
+object Page {
+  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 Superscript(in) => inlineToStr(in)
+    case Subscript(in) => inlineToStr(in)
+    case Link(raw, title) => inlineToStr(title)
+    case Monospace(in) => inlineToStr(in)
+    case Text(text) => text
+    case Summary(in) => inlineToStr(in)
+    case HtmlTag(tag) => "<[^>]*>".r.replaceAllIn(tag, "")
+    case EntityLink(Text(text), _) => text
   }
 }

src/scaladoc/scala/tools/nsc/doc/html/page/Entity.scala

@@ -90,13 +90,13 @@ trait EntityPage extends HtmlPage {
                           mbr match {
                             case dtpl: DocTemplateEntity =>
                               dtpl.companion.fold(<span class="separator"></span>) { c: DocTemplateEntity =>
-                                <a class="object" href={relativeLinkTo(c)} title={c.comment.fold("")(com => inlineToStr(com.short))}></a>
+                                <a class="object" href={relativeLinkTo(c)} title={c.comment.fold("")(com => Page.inlineToStr(com.short))}></a>
                               }
                             case _ => <span class="separator"></span>
                           }
                         }
-                        <a class={mbr.kind} href={relativeLinkTo(mbr)} title={mbr.comment.fold("")(com => inlineToStr(com.short))}></a>
-                        <a href={relativeLinkTo(mbr)} title={mbr.comment.fold("")(com => inlineToStr(com.short))}>
+                        <a class={mbr.kind} href={relativeLinkTo(mbr)} title={mbr.comment.fold("")(com => Page.inlineToStr(com.short))}></a>
+                        <a href={relativeLinkTo(mbr)} title={mbr.comment.fold("")(com => Page.inlineToStr(com.short))}>
                           {mbr.name}
                         </a>
                       </li>
@@ -897,7 +897,7 @@ trait EntityPage extends HtmlPage {
             }
           }
           if (!nameLink.isEmpty)
-            <a title={mbr.comment.fold("")(c => inlineToStr(c.short))} href={nameLink}>
+            <a title={mbr.comment.fold("")(c => Page.inlineToStr(c.short))} href={nameLink}>
               {nameHtml}
             </a>
           else nameHtml
@@ -1065,7 +1065,7 @@ trait EntityPage extends HtmlPage {
     body.blocks flatMap (blockToStr(_)) mkString ""
 
   private def blockToStr(block: comment.Block): String = block match {
-    case comment.Paragraph(in) => inlineToStr(in)
+    case comment.Paragraph(in) => Page.inlineToStr(in)
     case _ => block.toString
   }
 

src/scaladoc/scala/tools/nsc/doc/html/page/IndexScript.scala

@@ -87,7 +87,7 @@ class IndexScript(universe: doc.Universe) extends Page {
 
   /** Gets the short description i.e. the first sentence of the docstring */
   def shortDesc(mbr: MemberEntity): String = mbr.comment.fold("") { c =>
-    inlineToStr(c.short).replaceAll("\n", "")
+    Page.inlineToStr(c.short).replaceAll("\n", "")
   }
 
   /** Returns the json representation of the supplied members */

test/scaladoc/run/inlineToStr-strips-unwanted-text.check

@@ -0,0 +1,13 @@
+Chain(List(Chain(List(Text(This comment contains ), Superscript(Text(superscript))))))
+Chain(List(Chain(List(Text(This comment contains ), Subscript(Text(subscript))))))
+Chain(List(Chain(List(Text(This comment contains a link ), Link(https://scala.epfl.ch/,Text(https://scala.epfl.ch/))))))
+Chain(List(Chain(List(Text(This comment contains an ), HtmlTag(<strong>html tag</strong>)))))
+Chain(List(Chain(List(Text(This comment contains a), HtmlTag(<br>), Text( single html tag)))))
+Chain(List(Chain(List(Text(This comment contains nested ), HtmlTag(<strong>html<br> tags</strong>)))))
+This comment contains superscript
+This comment contains subscript
+This comment contains a link https://scala.epfl.ch/
+This comment contains an html tag
+This comment contains a single html tag
+This comment contains nested html tags
+Done.

test/scaladoc/run/inlineToStr-strips-unwanted-text.scala

@@ -0,0 +1,51 @@
+import scala.tools.nsc.doc.html.Page
+import scala.tools.nsc.doc.model._
+import scala.tools.partest.ScaladocModelTest
+
+object Test extends ScaladocModelTest {
+
+  override def code = """
+  /** This comment contains ^superscript^ */
+  class Foo {
+    /** This comment contains ,,subscript,, */
+    def bar = ???
+
+    /** This comment contains a link [[https://scala.epfl.ch/]] */
+    def baz = ???
+
+    /** This comment contains an <strong>html tag</strong> */
+    def qux = ???
+
+    /** This comment contains a<br> single html tag */
+    def quux = ???
+
+    /** This comment contains nested <strong>html<br> tags</strong> */
+    def quuz = ???
+  }
+  """
+  def scaladocSettings = ""
+
+  def testModel(root: Package) = {
+    import scala.tools.nsc.doc.base.comment._
+    import access._
+
+    val foo = root._class("Foo")
+    val bar = foo._method("bar")
+    val baz = foo._method("baz")
+    val qux = foo._method("qux")
+    val quux = foo._method("quux")
+    val quuz = foo._method("quuz")
+    println(foo.comment.get.short)
+    println(bar.comment.get.short)
+    println(baz.comment.get.short)
+    println(qux.comment.get.short)
+    println(quux.comment.get.short)
+    println(quuz.comment.get.short)
+    println(Page.inlineToStr(foo.comment.get.short))
+    println(Page.inlineToStr(bar.comment.get.short))
+    println(Page.inlineToStr(baz.comment.get.short))
+    println(Page.inlineToStr(qux.comment.get.short))
+    println(Page.inlineToStr(quux.comment.get.short))
+    println(Page.inlineToStr(quuz.comment.get.short))
+  }
+}

test/scaladoc/run/shortDescription-annotation.scala

@@ -1,3 +1,4 @@
+import scala.tools.nsc.doc.html.Page
 import scala.tools.nsc.doc.model._
 import scala.tools.partest.ScaladocModelTest
 
@@ -26,30 +27,18 @@ object Test extends ScaladocModelTest {
     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)
+    val classDesc = Page.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)
+    val fooDesc = Page.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)
+    val gooDesc = Page.inlineToStr(foo._method("goo").comment.get.short)
     assert(gooDesc == "This comment should appear", gooDesc)
   }
 }