Merge pull request #13933 from dotty-staging/scaladoc/comment-renderi…

…ng-fix

Scaladoc: Add support for tables in wiki syntax

scaladoc-testcases/src/example/level2/Documentation.scala

@@ -149,6 +149,19 @@ abstract class Documentation[T, A <: Int, B >: String, -X, +Y](c1: String, val c
     */
   def loremIpsum[T](a: T): Map[T, T] = ???
 
+  /**
+    *  &nbsp;
+    * | How to convert ... | to a [[PartialFunction]] | to an optional [[Function]] | to an extractor |
+    * | :---:  | ---  | --- | --- |
+    * | from a [[PartialFunction]] | [[Predef.identity]] | [[lift]] | [[Predef.identity]] |
+    * | from optional [[Function]] | [[Function1.UnliftOps#unlift]] or [[Function.unlift]] | [[Predef.identity]] | [[Function1.UnliftOps#unlift]] |
+    * | from an extractor | `{ case extractor(x) => x }` | `extractor.unapply _` | [[Predef.identity]] |
+    *  &nbsp;
+    *
+    * @syntax wiki
+    */
+  def table(foo: String) = ???
+
   protected[example] val valWithScopeModifier = ???
   protected[this] val valWithScopeModifierThis = ???
 

scaladoc/src/dotty/tools/scaladoc/renderers/DocRenderer.scala

@@ -42,6 +42,16 @@ class DocRender(signatureRenderer: SignatureRenderer)(using DocContext):
         val tooltip = s"Problem linking $query: $msg"
         signatureRenderer.unresolvedLink(linkBody(query), titleAttr :=  tooltip)
 
+  private def renderHeader(header: Row): AppliedTag =
+    tr(
+      header.cells.map(c => th(c.blocks.map(renderElement)))
+    )
+
+  private def renderRow(row: Row): AppliedTag =
+    tr(
+      row.cells.map(c => td(c.blocks.map(renderElement)))
+    )
+
   private def renderElement(e: WikiDocElement): AppliedTag = e match
     case Title(text, level) =>
       val content = renderElement(text)
@@ -55,6 +65,15 @@ class DocRender(signatureRenderer: SignatureRenderer)(using DocContext):
     case Paragraph(text) => p(renderElement(text))
     case Code(data: String) => pre(code(raw(data.escapeReservedTokens))) // TODO add classes
     case HorizontalRule => hr
+    case Table(header, columns, rows) =>
+      table(
+        thead(
+          renderHeader(header)
+        ),
+        tbody(
+          rows.map(renderRow)
+        )
+      )
 
     case UnorderedList(items) => ul(listItems(items))
     case OrderedList(items, style) => ol(listItems(items)) // TODO use style

scaladoc/src/dotty/tools/scaladoc/tasty/comments/Comments.scala

@@ -235,6 +235,7 @@ class WikiCommentParser(repr: Repr)(using DocContext)
     case wiki.OrderedList(elems, _) => elems.headOption.fold("")(flatten)
     case wiki.DefinitionList(items) => items.headOption.fold("")(e => flatten(e._1))
     case wiki.HorizontalRule => ""
+    case wiki.Table(header, columns, rows) => (header +: rows).flatMap(_.cells).flatMap(_.blocks).map(flatten).mkString
 
   def markupToString(str: wiki.Body) = str.blocks.headOption.fold("")(flatten)
 

scaladoc/src/dotty/tools/scaladoc/tasty/comments/wiki/Entities.scala

@@ -50,6 +50,15 @@ final case class UnorderedList(items: Seq[Block]) extends Block
 final case class OrderedList(items: Seq[Block], style: String) extends Block
 final case class DefinitionList(items: SortedMap[Inline, Block]) extends Block
 object HorizontalRule extends Block
+final case class Table(header: Row, columnOptions: Seq[ColumnOption], rows: Seq[Row]) extends Block
+final case class ColumnOption(option: 'L' | 'C' | 'R')
+object ColumnOption {
+  val ColumnOptionLeft = ColumnOption('L')
+  val ColumnOptionCenter = ColumnOption('C')
+  val ColumnOptionRight = ColumnOption('R')
+}
+final case class Row(cells: Seq[Cell])
+final case class Cell(blocks: Seq[Block])
 
 /** An section of text inside a block, possibly with formatting. */
 sealed abstract class Inline extends WikiDocElement: