Format documentation in REPL

Author: Duhemm

compiler/src/dotty/tools/dotc/util/ParsedComment.scala

@@ -4,7 +4,9 @@ import dotty.tools.dotc.core.Comments.{Comment, CommentsContext}
 import dotty.tools.dotc.core.Contexts.Context
 import dotty.tools.dotc.core.Names.TermName
 import dotty.tools.dotc.core.Symbols._
+import dotty.tools.dotc.printing.SyntaxHighlighting
 
+import scala.Console.{BOLD, RESET, UNDERLINED}
 import scala.collection.immutable.ListMap
 import scala.util.matching.Regex
 
@@ -50,7 +52,7 @@ class ParsedComment(val comment: Comment) {
    *
    * The different sections are formatted according to the mapping in `knownTags`.
    */
-  def renderAsMarkdown: String = {
+  def renderAsMarkdown(implicit ctx: Context): String = {
     val buf = new StringBuilder
     buf.append(mainDoc + System.lineSeparator + System.lineSeparator)
     val groupedSections = CommentParsing.groupedSections(content, tagIndex)
@@ -131,12 +133,12 @@ object ParsedComment {
    * @param items The items to format into a list.
    * @return A markdown list of descriptions.
    */
-  private def toDescriptionList(items: List[String]): String = {
+  private def toDescriptionList(ctx: Context, items: List[String]): String = {
     val formattedItems = items.map { p =>
       val name :: rest = p.split(" ", 2).toList
-      s"**$name** ${rest.mkString("").trim}"
+      s"${bold(name)(ctx)} ${rest.mkString("").trim}"
     }
-    toMarkdownList(formattedItems)
+    toMarkdownList(ctx, formattedItems)
   }
 
   /**
@@ -145,34 +147,41 @@ object ParsedComment {
    * @param items The items to put in a list.
    * @return The list of items, in markdown.
    */
-  private def toMarkdownList(items: List[String]): String = {
+  private def toMarkdownList(ctx: Context, items: List[String]): String = {
     val formattedItems = items.map(_.lines.mkString(System.lineSeparator + "   "))
     formattedItems.mkString(" - ", System.lineSeparator + " - ", "")
   }
 
   /**
-   * Wrap each of `snippets` into a markdown code fence, using `language`. All the code fences are
-   * put into a markdown list.
+   * If the color is enabled, add syntax highlighting to each of `snippets`, otherwise wrap each
+   * of them in a markdown code fence.
+   * The results are put into a markdown list.
    *
    * @param language The language to use for the code fences
    * @param snippets The list of snippets to format.
    * @return A markdown list of code fences.
    * @see toCodeFence
    */
-  private def toCodeFences(language: String)(snippets: List[String]): String =
-    toMarkdownList(snippets.map(toCodeFence(language)))
+  private def toCodeFences(language: String)(ctx: Context, snippets: List[String]): String =
+    toMarkdownList(ctx, snippets.map(toCodeFence(language)(ctx, _)))
 
   /**
-   * Wraps `snippet` in a markdown code fence, using `language`.
+   * Formats `snippet` for display. If the color is enabled, the syntax is highlighted,
+   * otherwise the snippet is wrapped in a markdown code fence.
    *
    * @param language The language to use.
    * @param snippet  The code snippet
    * @return `snippet`, wrapped in a code fence.
    */
-  private def toCodeFence(language: String)(snippet: String): String =
-    s"""```$language
-       |$snippet
-       |```""".stripMargin
+  private def toCodeFence(language: String)(ctx: Context, snippet: String): String = {
+    if (colorEnabled(ctx)) {
+      SyntaxHighlighting.highlight(snippet)(ctx)
+    } else {
+      s"""```$language
+         |$snippet
+         |```""".stripMargin
+    }
+  }
 
   /**
    * Format the elements of documentation associated with a given tag using `fn`, and starts the
@@ -181,22 +190,41 @@ object ParsedComment {
    * @param title The title to give to the formatted items.
    * @param fn    The formatting function to use.
    */
-  private case class TagFormatter(title: String, fn: List[String] => String) {
+  private case class TagFormatter(title: String, fn: (Context, List[String]) => String) {
 
     /**
      * Format `item` using `fn` if `items` is not empty.
      *
      * @param items The items to format
      * @return If items is not empty, the items formatted using `fn`.
      */
-    def apply(items: List[String]): Option[String] = items match {
+    def apply(items: List[String])(implicit ctx: Context): Option[String] = items match {
       case Nil =>
         None
       case items =>
-        Some(s"""#### $title:
-                |${fn(items)}
+        Some(s"""${heading(title)}:
+                |${fn(ctx, items)}
                 |""".stripMargin)
     }
   }
 
+  /** Is the color enabled in the context? */
+  private def colorEnabled(implicit ctx: Context): Boolean =
+    ctx.settings.color.value != "never"
+
+  /**
+   * If the color is enabled, underline `str`, otherwise make it a markdown header by
+   * prepending `####`.
+   */
+  private def heading(str: String)(implicit ctx: Context): String = {
+    if (colorEnabled) s"$UNDERLINED$str$RESET"
+    else s"#### $str"
+  }
+
+  /** Show `str` in bold */
+  private def bold(str: String)(implicit ctx: Context): String = {
+    if (colorEnabled) s"$BOLD$str$RESET"
+    else s"**$str**"
+  }
+
 }

compiler/src/dotty/tools/repl/ReplCompiler.scala

@@ -15,7 +15,7 @@ import dotty.tools.dotc.reporting.diagnostic.messages
 import dotty.tools.dotc.transform.PostTyper
 import dotty.tools.dotc.typer.ImportInfo
 import dotty.tools.dotc.util.Positions._
-import dotty.tools.dotc.util.SourceFile
+import dotty.tools.dotc.util.{ParsedComment, SourceFile}
 import dotty.tools.dotc.{CompilationUnit, Compiler, Run}
 import dotty.tools.repl.results._
 
@@ -196,10 +196,8 @@ class ReplCompiler extends Compiler {
           val symbols = extractSymbols(stat)
           val doc = for {
             sym <- symbols
-            docCtx <- ctx.docCtx
-            comment <- docCtx.docstring(sym)
-            body <- comment.expandedBody
-          } yield body
+            comment <- ParsedComment.docOf(sym)
+          } yield comment.renderAsMarkdown
 
           if (doc.hasNext) doc.next()
           else s"// No doc for `$expr`"

compiler/src/dotty/tools/repl/ReplDriver.scala

@@ -351,7 +351,7 @@ class ReplDriver(settings: Array[String],
     case DocOf(expr) =>
       compiler.docOf(expr)(newRun(state)).fold(
         displayErrors,
-        res => out.println(SyntaxHighlighting.highlight(res)(state.context))
+        res => out.println(res)
       )
       state
 

compiler/test/dotty/tools/repl/DocTests.scala

@@ -8,92 +8,92 @@ class DocTests extends ReplTest {
 
   @Test def docOfDef =
     eval("/** doc */ def foo = 0").andThen { implicit s =>
-      assertEquals("/** doc */", doc("foo"))
+      assertEquals("doc", doc("foo"))
     }
 
   @Test def docOfVal =
     eval("/** doc */ val foo = 0").andThen { implicit s =>
-      assertEquals("/** doc */", doc("foo"))
+      assertEquals("doc", doc("foo"))
     }
 
   @Test def docOfObject =
     eval("/** doc */ object Foo").andThen { implicit s =>
-      assertEquals("/** doc */", doc("Foo"))
+      assertEquals("doc", doc("Foo"))
     }
 
   @Test def docOfClass =
     eval("/** doc */ class Foo").andThen { implicit s =>
-      assertEquals("/** doc */", doc("new Foo"))
+      assertEquals("doc", doc("new Foo"))
     }
 
   @Test def docOfTrait =
     eval("/** doc */ trait Foo").andThen { implicit s =>
-      assertEquals("/** doc */", doc("new Foo"))
+      assertEquals("doc", doc("new Foo"))
     }
 
   @Test def docOfDefInObject =
     eval("object O { /** doc */ def foo = 0 }").andThen { implicit s =>
-      assertEquals("/** doc */", doc("O.foo"))
+      assertEquals("doc", doc("O.foo"))
     }
 
   @Test def docOfValInObject =
     eval("object O { /** doc */ val foo = 0 }").andThen { implicit s =>
-      assertEquals("/** doc */", doc("O.foo"))
+      assertEquals("doc", doc("O.foo"))
     }
 
   @Test def docOfObjectInObject =
     eval("object O { /** doc */ object Foo }").andThen { implicit s =>
-      assertEquals("/** doc */", doc("O.Foo"))
+      assertEquals("doc", doc("O.Foo"))
     }
 
   @Test def docOfClassInObject =
     eval("object O { /** doc */ class Foo }").andThen { implicit s =>
-      assertEquals("/** doc */", doc("new O.Foo"))
+      assertEquals("doc", doc("new O.Foo"))
     }
 
   @Test def docOfTraitInObject =
     eval("object O { /** doc */ trait Foo }").andThen { implicit s =>
-      assertEquals("/** doc */", doc("new O.Foo"))
+      assertEquals("doc", doc("new O.Foo"))
     }
 
   @Test def docOfDefInClass =
     eval(
       """class C { /** doc */ def foo = 0 }
         |val c = new C
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** doc */", doc("c.foo"))
+      assertEquals("doc", doc("c.foo"))
     }
 
   @Test def docOfValInClass =
     eval(
       """class C { /** doc */ val foo = 0 }
         |val c = new C
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** doc */", doc("c.foo"))
+      assertEquals("doc", doc("c.foo"))
     }
 
   @Test def docOfObjectInClass =
     eval(
       """class C { /** doc */ object Foo }
         |val c = new C
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** doc */", doc("c.Foo"))
+      assertEquals("doc", doc("c.Foo"))
     }
 
   @Test def docOfClassInClass =
     eval(
       """class C { /** doc */ class Foo }
         |val c = new C
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** doc */", doc("new c.Foo"))
+      assertEquals("doc", doc("new c.Foo"))
     }
 
   @Test def docOfTraitInClass =
     eval(
       """class C { /** doc */ trait Foo }
         |val c = new C
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** doc */", doc("new c.Foo"))
+      assertEquals("doc", doc("new c.Foo"))
     }
 
   @Test def docOfOverloadedDef =
@@ -103,16 +103,16 @@ class DocTests extends ReplTest {
         |  /** doc1 */ def foo(x: String) = x
         |}
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** doc0 */", doc("O.foo(_: Int)"))
-      assertEquals("/** doc1 */", doc("O.foo(_: String)"))
+      assertEquals("doc0", doc("O.foo(_: Int)"))
+      assertEquals("doc1", doc("O.foo(_: String)"))
     }
 
   @Test def docOfInherited =
     eval(
       """class C { /** doc */ def foo = 0 }
         |object O extends C
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** doc */", doc("O.foo"))
+      assertEquals("doc", doc("O.foo"))
     }
 
   @Test def docOfOverride =
@@ -126,8 +126,8 @@ class DocTests extends ReplTest {
         |  /** overridden doc */ override def foo(x: String): String = x
         |}
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** doc0 */", doc("O.foo(_: Int)"))
-      assertEquals("/** overridden doc */", doc("O.foo(_: String)"))
+      assertEquals("doc0", doc("O.foo(_: Int)"))
+      assertEquals("overridden doc", doc("O.foo(_: String)"))
     }
 
   @Test def docOfOverrideObject =
@@ -142,8 +142,8 @@ class DocTests extends ReplTest {
         |  }
         |}
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** companion */", doc("O.foo"))
-      assertEquals("/** doc0 */", doc("O.foo.bar"))
+      assertEquals("companion", doc("O.foo"))
+      assertEquals("doc0", doc("O.foo.bar"))
     }
 
   @Test def docIsCooked =
@@ -157,7 +157,7 @@ class DocTests extends ReplTest {
         |  def hello = "world"
         |}
       """.stripMargin).andThen { implicit s =>
-      assertEquals("/** Expansion: some-value */", doc("Foo.hello"))
+      assertEquals("Expansion: some-value", doc("Foo.hello"))
     }
 
   private def eval(code: String): State =

language-server/src/dotty/tools/languageserver/DottyLanguageServer.scala

@@ -607,7 +607,9 @@ object DottyLanguageServer {
     }
   }
 
-  private def hoverContent(typeInfo: Option[String], comment: Option[ParsedComment]): lsp4j.MarkupContent = {
+  private def hoverContent(typeInfo: Option[String],
+                           comment: Option[ParsedComment]
+                          )(implicit ctx: Context): lsp4j.MarkupContent = {
     val buf = new StringBuilder
     typeInfo.foreach { info =>
       buf.append(s"""```scala