Fix #5508: Add Completion structure

One `Completion` represents one completion results that should be
included in the list of completion options. It can represent zero
symbols (for instance, a wildcard import), or more than one (a class and
its companion object). Each `Completion` also has a `description` which
should be displayed in the tool that shows the completion candidates.

Fixes #5508

Author: Duhemm

compiler/src/dotty/tools/dotc/interactive/Completion.scala

@@ -20,6 +20,17 @@ import dotty.tools.dotc.util.{NoSourcePosition, SourcePosition}
 
 import scala.collection.mutable
 
+/**
+ * One of the results of a completion query.
+ *
+ * @param label         The label of this completion result, or the text that this completion result
+ *                      should insert in the scope where the completion request happened.
+ * @param description   The description of this completion result: the fully qualified name for
+ *                      types, or the type for terms.
+ * @param symbols       The symbols that are matched by this completion result.
+ */
+case class Completion(label: String, description: String, symbols: List[Symbol])
+
 object Completion {
 
   import dotty.tools.dotc.ast.tpd._
@@ -28,7 +39,7 @@ object Completion {
    *
    *  @return offset and list of symbols for possible completions
    */
-  def completions(pos: SourcePosition)(implicit ctx: Context): (Int, List[Symbol]) = {
+  def completions(pos: SourcePosition)(implicit ctx: Context): (Int, List[Completion]) = {
     val path = Interactive.pathTo(ctx.compilationUnit.tpdTree, pos.pos)
     computeCompletions(pos, path)(Interactive.contextOfPath(path))
   }
@@ -100,7 +111,7 @@ object Completion {
     new CompletionBuffer(mode, prefix, pos)
   }
 
-  private def computeCompletions(pos: SourcePosition, path: List[Tree])(implicit ctx: Context): (Int, List[Symbol]) = {
+  private def computeCompletions(pos: SourcePosition, path: List[Tree])(implicit ctx: Context): (Int, List[Completion]) = {
 
     val offset = completionOffset(path)
     val buffer = completionBuffer(path, pos)
@@ -131,15 +142,27 @@ object Completion {
     /**
      * Return the list of symbols that shoudl be included in completion results.
      *
-     * If the mode is `Import` and several symbols share the same name, the type symbols are
-     * preferred over term symbols.
+     * If several symbols share the same name, the type symbols appear before term symbols inside
+     * the same `Completion`.
+     */
+    def getCompletions(implicit ctx: Context): List[Completion] = {
+      val groupedSymbols = completions.toList.groupBy(_.name.stripModuleClassSuffix.toSimpleName).toList
+      groupedSymbols.map { case (name, symbols) =>
+        val typesFirst = symbols.sortWith((s, _) => s.isType)
+        // Use distinct to remove duplicates with class, module class, etc.
+        val descriptions = typesFirst.map(description).distinct.mkString(", ")
+        Completion(name.toString, descriptions, typesFirst)
+      }
+    }
+
+    /**
+     * A description for `sym`.
+     *
+     * For types, show the symbol's full name, or its type for term symbols.
      */
-    def getCompletions(implicit ctx: Context): List[Symbol] = {
-      // Show only the type symbols when there are multiple options with the same name
-      completions.toList.groupBy(_.name.stripModuleClassSuffix.toSimpleName).mapValues {
-        case sym :: Nil => sym :: Nil
-        case syms => syms.filter(_.isType)
-      }.values.flatten.toList
+    private def description(sym: Symbol)(implicit ctx: Context): String = {
+      if (sym.isType) sym.showFullName
+      else sym.info.widenTermRefExpr.show
     }
 
     /**

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

@@ -149,8 +149,8 @@ class ReplDriver(settings: Array[String],
 
   /** Extract possible completions at the index of `cursor` in `expr` */
   protected[this] final def completions(cursor: Int, expr: String, state0: State): List[Candidate] = {
-    def makeCandidate(completion: Symbol)(implicit ctx: Context) = {
-      val displ = completion.name.toString
+    def makeCandidate(completion: Completion)(implicit ctx: Context) = {
+      val displ = completion.label
       new Candidate(
         /* value    = */ displ,
         /* displ    = */ displ, // displayed value

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

@@ -780,8 +780,8 @@ object DottyLanguageServer {
       symbol.owner == ctx.definitions.EmptyPackageClass
   }
 
-  /** Create an lsp4j.CompletionItem from a Symbol */
-  def completionItem(sym: Symbol)(implicit ctx: Context): lsp4j.CompletionItem = {
+  /** Create an lsp4j.CompletionItem from a completion result */
+  def completionItem(completion: Completion)(implicit ctx: Context): lsp4j.CompletionItem = {
     def completionItemKind(sym: Symbol)(implicit ctx: Context): lsp4j.CompletionItemKind = {
       import lsp4j.{CompletionItemKind => CIK}
 
@@ -799,15 +799,20 @@ object DottyLanguageServer {
         CIK.Field
     }
 
-    val label = sym.name.show
-    val item = new lsp4j.CompletionItem(label)
-    val detail = if (sym.isType) sym.showFullName else sym.info.widenTermRefExpr.show
-    item.setDetail(detail)
-    ParsedComment.docOf(sym).foreach { doc =>
-      item.setDocumentation(markupContent(doc.renderAsMarkdown))
+    val item = new lsp4j.CompletionItem(completion.label)
+    item.setDetail(completion.description)
+
+    val documentation = for {
+      sym <- completion.symbols
+      doc <- ParsedComment.docOf(sym)
+    } yield doc
+
+    if (documentation.nonEmpty) {
+      item.setDocumentation(hoverContent(None, documentation))
     }
-    item.setDeprecated(sym.isDeprecated)
-    item.setKind(completionItemKind(sym))
+
+    item.setDeprecated(completion.symbols.forall(_.isDeprecated))
+    completion.symbols.headOption.foreach(s => item.setKind(completionItemKind(s)))
     item
   }