[clangd] Render code complete documentation as plaintext/markdown.

[sammccall]

Summary

Structure is parsed from the raw comment using the existing heuristics used
for hover.

[kadircet]

thanks, mostly LG apart from dropping of white-space only comments.

clang-tools-extra/clangd/CodeComplete.cpp

377

why do we ignore whitespace only comments now ?

nit: early exit;

if(Doc.trim().empty())
  return;
...

clang-tools-extra/clangd/Hover.h

83

yeah was about to say that :D what about formattedstring.h with a different name like parseRaw ?

clang-tools-extra/clangd/Protocol.cpp

317

why not just if (fromJson(Format, R.CompletionDocFormat) ?

342–343

i know it is not related to this change, but you've touched it :P so same as above, maybe just fromJson(Format, R.HoverContentFormat)

clang-tools-extra/clangd/unittests/CodeCompleteTests.cpp

835

no action needed here(apart from maybe filing a bug), but this one looks like a hard-break to me, as the line below is longer in width. why is parseDocumentation not preserving it?

It might also be the case that i am just wrong, as I didn't check the line break heuristics :D

[sammccall]

clang-tools-extra/clangd/CodeComplete.cpp

377

why do we ignore whitespace only comments now ?

Having the empty-check at all is because the type changed from string-or-empty to document-or-null.

I threw the trim in "while there" because ws-only seems "functionally-empty" - happy to revert on the basis of "unrelated change" but is there an actual reason to include these? Or just the wrong layer?

clang-tools-extra/clangd/Hover.h

83

I'm iffy on the conceptual dependency - FormattedString has a clear responsibility and is a good candidate for moving to Support.

The actual interface and deps are fine today, but it's going to get more complicated when (if?) we want to have it fish out param docs and return value docs for attaching to hover.

Anyway it's definitely an option, but I wanted to do it separately because it's a refactoring change and also not totally obvious where the right place is.

clang-tools-extra/clangd/Protocol.cpp

317

Yeah, that's better.

(There's no contract that fromJSON leaves the output unchanged when it returns false, and sometimes it doesn't e.g. for objects constructed in place. But it's an enum, what's the worst that could happen...)

clang-tools-extra/clangd/unittests/CodeCompleteTests.cpp

835

This isn't implemented, though was discussed. Not sure how much it adds in practice when we already have the punctuation rule.

Added a comment to isHardLineBreakAfter in Hover.cpp.

[sammccall]

address comments

[kadircet]

LGTM thanks!

clang-tools-extra/clangd/CodeComplete.cpp

377

the trimming behaviour is already performed by FormattedString in appendText, as we cannonicalizeSpaces and ignore the chunk if it is whitespace only during the process. so i was confused to see it here too.

Previous code would accept and surface white-space only comment as-is. Now we'll ignore such comments (other options is displaying an empty comment).

I suppose doing the check below in LSP conversion might be more clear, since from code completion's perspective we've actually found a comment unless it is empty.

clang-tools-extra/clangd/Hover.h

83

SGTM.

clang-tools-extra/clangd/unittests/CodeCompleteTests.cpp

835

oh i see. i must be remembering the discussion, thanks!

[sammccall]

clang-tools-extra/clangd/CodeComplete.cpp

377

the trimming behaviour is already performed by FormattedString in appendText, as we cannonicalizeSpaces and ignore the chunk if it is whitespace only during the process. so i was confused to see it here too.

Yeah, this is too late - we want to avoid creating the markup::Document at all.

Nevertheless, reverted the change, it's basically unrelated and I don't have a test.

clang-tools-extra/clangd/ClangdLSPServer.cpp

Server.emplace(*CDB, FSProvider, ClangdServerOpts,
                    static_cast<ClangdServer::Callbacks *>(this));
   }
   applyConfiguration(Params.initializationOptions.ConfigSettings);
 
   CCOpts.EnableSnippets = Params.capabilities.CompletionSnippets;
   CCOpts.IncludeFixIts = Params.capabilities.CompletionFixes;
   if (!CCOpts.BundleOverloads.hasValue())
     CCOpts.BundleOverloads = Params.capabilities.HasSignatureHelp;
+  CCOpts.DocumentationFormat =
+      Params.capabilities.CompletionDocumentationFormat;
   DiagOpts.EmbedFixesInDiagnostics = Params.capabilities.DiagnosticFixes;
   DiagOpts.SendDiagnosticCategory = Params.capabilities.DiagnosticCategory;
   DiagOpts.EmitRelatedLocations =
       Params.capabilities.DiagnosticRelatedInformation;
   if (Params.capabilities.WorkspaceSymbolKinds)
     SupportedSymbolKinds |= *Params.capabilities.WorkspaceSymbolKinds;
   if (Params.capabilities.CompletionItemKinds)
     SupportedCompletionItemKinds |= *Params.capabilities.CompletionItemKinds;

clang-tools-extra/clangd/CodeComplete.h

 // After "std::string S; S." we might suggest members of std::string.
 // Signature help describes the parameters of a function as you type them.
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_CODECOMPLETE_H
 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_CODECOMPLETE_H
 
+#include "FormattedString.h"
 #include "Headers.h"
 #include "Protocol.h"
 #include "Quality.h"
 #include "index/Index.h"
 #include "index/Symbol.h"
 #include "index/SymbolOrigin.h"
 #include "support/Logger.h"
 #include "support/Path.h"
struct CodeCompleteOptions {
   /// (In practice, ClangdLSPServer enables bundling if the client claims
   /// to supports signature help).
   llvm::Optional<bool> BundleOverloads;
 
   /// Limit the number of results returned (0 means no limit).
   /// If more results are available, we set CompletionList.isIncomplete.
   size_t Limit = 0;
 
+  /// Whether to present doc comments as plain-text or markdown.
+  MarkupKind DocumentationFormat = MarkupKind::PlainText;
+
   enum IncludeInsertion {
     IWYU,
     NeverInsert,
   } InsertIncludes = IncludeInsertion::IWYU;
 
   /// A visual indicator to prepend to the completion label to indicate whether
   /// completion result would trigger an #include insertion or not.
   struct IncludeInsertionIndicator {
struct CodeCompletion {
   // Text that must be inserted before the name, and displayed (e.g. base::).
   std::string RequiredQualifier;
   // Details to be displayed following the name. Not inserted.
   std::string Signature;
   // Text to be inserted following the name, in snippet format.
   std::string SnippetSuffix;
   // Type to be displayed for this completion.
   std::string ReturnType;
-  std::string Documentation;
+  // The parsed documentation comment.
+  llvm::Optional<markup::Document> Documentation;
   CompletionItemKind Kind = CompletionItemKind::Missing;
   // This completion item may represent several symbols that can be inserted in
   // the same way, such as function overloads. In this case BundleSize > 1, and
   // the following fields are summaries:
   //  - Signature is e.g. "(...)" for functions.
   //  - SnippetSuffix is similarly e.g. "(${0})".
   //  - ReturnType may be empty
   //  - Documentation may be from one symbol, or a combination of several

clang-tools-extra/clangd/CodeComplete.cpp

 #include "AST.h"
 #include "CodeCompletionStrings.h"
 #include "Compiler.h"
 #include "Diagnostics.h"
 #include "ExpectedTypes.h"
 #include "FileDistance.h"
 #include "FuzzyMatch.h"
 #include "Headers.h"
+#include "Hover.h"
 #include "Preamble.h"
 #include "Protocol.h"
 #include "Quality.h"
 #include "SourceCode.h"
 #include "TUScheduler.h"
 #include "URI.h"
 #include "index/Index.h"
 #include "index/Symbol.h"
if (C.SemaResult) {
       getSignature(*SemaCCS, &S.Signature, &S.SnippetSuffix,
                    &Completion.RequiredQualifier, IsPattern);
       S.ReturnType = getReturnType(*SemaCCS);
     } else if (C.IndexResult) {
       S.Signature = std::string(C.IndexResult->Signature);
       S.SnippetSuffix = std::string(C.IndexResult->CompletionSnippetSuffix);
       S.ReturnType = std::string(C.IndexResult->ReturnType);
     }
-    if (ExtractDocumentation && Completion.Documentation.empty()) {
-      if (C.IndexResult)
-        Completion.Documentation = std::string(C.IndexResult->Documentation);
-      else if (C.SemaResult)
-        Completion.Documentation = getDocComment(*ASTCtx, *C.SemaResult,
-                                                 /*CommentsFromHeader=*/false);
+    if (ExtractDocumentation && !Completion.Documentation) {
+      auto SetDoc = [&](llvm::StringRef Doc) {
+        if (!Doc.empty()) {
+          Completion.Documentation.emplace();
+          parseDocumentation(Doc, *Completion.Documentation);
+        }
+      };
+      if (C.IndexResult) {
+        SetDoc(C.IndexResult->Documentation);
+      } else if (C.SemaResult) {
+        SetDoc(getDocComment(*ASTCtx, *C.SemaResult,
+                             /*CommentsFromHeader=*/false));
+      }
     }
   }
 
   CodeCompletion build() {
     Completion.ReturnType = summarizeReturnType();
     Completion.Signature = summarizeSignature();
     Completion.SnippetSuffix = summarizeSnippet();
     Completion.BundleSize = Bundled.size();
CompletionItem CodeCompletion::render(const CodeCompleteOptions &Opts) const {
 
   LSP.kind = Kind;
   LSP.detail = BundleSize > 1
                    ? std::string(llvm::formatv("[{0} overloads]", BundleSize))
                    : ReturnType;
   LSP.deprecated = Deprecated;
   if (InsertInclude)
     LSP.detail += "\n" + InsertInclude->Header;
-  LSP.documentation = Documentation;
+  if (Documentation) {
+    LSP.documentation.emplace();
+    switch (Opts.DocumentationFormat) {
+    case MarkupKind::PlainText:
+      LSP.documentation->value = Documentation->asPlainText();
+      break;
+    case MarkupKind::Markdown:
+      LSP.documentation->value = Documentation->asMarkdown();
+      break;
+    }
+    LSP.documentation->kind = Opts.DocumentationFormat;
+  }
   LSP.sortText = sortText(Score.Total, Name);
   LSP.filterText = Name;
   LSP.textEdit = {CompletionTokenRange, RequiredQualifier + Name};
   // Merge continuous additionalTextEdits into main edit. The main motivation
   // behind this is to help LSP clients, it seems most of them are confused when
   // they are provided with additionalTextEdits that are consecutive to main
   // edit.
   // Note that we store additional text edits from back to front in a line. That

clang-tools-extra/clangd/FormattedString.h

 
 /// Holds text and knows how to lay it out. Multiple blocks can be grouped to
 /// form a document. Blocks include their own trailing newlines, container
 /// should trim them if need be.
 class Block {
 public:
   virtual void renderMarkdown(llvm::raw_ostream &OS) const = 0;
   virtual void renderPlainText(llvm::raw_ostream &OS) const = 0;
+  virtual std::unique_ptr<Block> clone() const = 0;
   std::string asMarkdown() const;
   std::string asPlainText() const;
 
   virtual bool isRuler() const { return false; }
   virtual ~Block() = default;
 };
 
 /// Represents parts of the markup that can contain strings, like inline code,
 /// code block or plain text.
 /// One must introduce different paragraphs to create separate blocks.
 class Paragraph : public Block {
 public:
   void renderMarkdown(llvm::raw_ostream &OS) const override;
   void renderPlainText(llvm::raw_ostream &OS) const override;
+  std::unique_ptr<Block> clone() const override;
 
   /// Append plain text to the end of the string.
   Paragraph &appendText(llvm::StringRef Text);
 
   /// Append inline code, this translates to the ` block in markdown.
   Paragraph &appendCode(llvm::StringRef Code);
 
 private:
   struct Chunk {
     enum {
       PlainText,
       InlineCode,
     } Kind = PlainText;
     std::string Contents;
   };
   std::vector<Chunk> Chunks;
 };
 
 /// Represents a sequence of one or more documents. Knows how to print them in a
 /// list like format, e.g. by prepending with "- " and indentation.
 class BulletList : public Block {
 public:
   void renderMarkdown(llvm::raw_ostream &OS) const override;
   void renderPlainText(llvm::raw_ostream &OS) const override;
+  std::unique_ptr<Block> clone() const override;
 
   class Document &addItem();
 
 private:
   std::vector<class Document> Items;
 };
 
 /// A format-agnostic representation for structured text. Allows rendering into
 /// markdown and plaintext.
 class Document {
 public:
+  Document() = default;
+  Document(const Document &Other) { *this = Other; }
+  Document &operator=(const Document &);
+  Document(Document &&) = default;
+  Document &operator=(Document &&) = default;
+
   /// Adds a semantical block that will be separate from others.
   Paragraph &addParagraph();
   /// Inserts a horizontal separator to the document.
   void addRuler();
   /// Adds a block of code. This translates to a ``` block in markdown. In plain
   /// text representation, the code block will be surrounded by newlines.
   void addCodeBlock(std::string Code, std::string Language = "cpp");
   /// Heading is a special type of paragraph that will be prepended with \p

clang-tools-extra/clangd/FormattedString.cpp

 class Ruler : public Block {
 public:
   void renderMarkdown(llvm::raw_ostream &OS) const override {
     // Note that we need an extra new line before the ruler, otherwise we might
     // make previous block a title instead of introducing a ruler.
     OS << "\n---\n";
   }
   void renderPlainText(llvm::raw_ostream &OS) const override { OS << '\n'; }
+  std::unique_ptr<Block> clone() const override {
+    return std::make_unique<Ruler>(*this);
+  }
   bool isRuler() const override { return true; }
 };
 
 class CodeBlock : public Block {
 public:
   void renderMarkdown(llvm::raw_ostream &OS) const override {
     std::string Marker = getMarkerForCodeBlock(Contents);
     // No need to pad from previous blocks, as they should end with a new line.
     OS << Marker << Language << '\n' << Contents << '\n' << Marker << '\n';
   }
 
   void renderPlainText(llvm::raw_ostream &OS) const override {
     // In plaintext we want one empty line before and after codeblocks.
     OS << '\n' << Contents << "\n\n";
   }
 
+  std::unique_ptr<Block> clone() const override {
+    return std::make_unique<CodeBlock>(*this);
+  }
+
   CodeBlock(std::string Contents, std::string Language)
       : Contents(std::move(Contents)), Language(std::move(Language)) {}
 
 private:
   std::string Contents;
   std::string Language;
 };
 
for (auto &C : Chunks) {
     Sep = " ";
   }
   // Paragraphs are translated into markdown lines, not markdown paragraphs.
   // Therefore it only has a single linebreak afterwards.
   // VSCode requires two spaces at the end of line to start a new one.
   OS << "  \n";
 }
 
+std::unique_ptr<Block> Paragraph::clone() const {
+  return std::make_unique<Paragraph>(*this);
+}
+
 void Paragraph::renderPlainText(llvm::raw_ostream &OS) const {
   llvm::StringRef Sep = "";
   for (auto &C : Chunks) {
     OS << Sep << C.Contents;
     Sep = " ";
   }
   OS << '\n';
 }
if (Norm.empty())
     return *this;
   Chunks.emplace_back();
   Chunk &C = Chunks.back();
   C.Contents = std::move(Norm);
   C.Kind = Chunk::InlineCode;
   return *this;
 }
 
+std::unique_ptr<Block> BulletList::clone() const {
+  return std::make_unique<BulletList>(*this);
+}
+
 class Document &BulletList::addItem() {
   Items.emplace_back();
   return Items.back();
 }
 
+Document &Document::operator=(const Document &Other) {
+  Children.clear();
+  for (const auto &C : Other.Children)
+    Children.push_back(C->clone());
+  return *this;
+}
+
 Paragraph &Document::addParagraph() {
   Children.push_back(std::make_unique<Paragraph>());
   return *static_cast<Paragraph *>(Children.back().get());
 }
 
 void Document::addRuler() { Children.push_back(std::make_unique<Ruler>()); }
 
 void Document::addCodeBlock(std::string Code, std::string Language) {

clang-tools-extra/clangd/Hover.h

struct HoverInfo {
   /// Contains the offset of fields within the enclosing class.
   llvm::Optional<uint64_t> Offset;
 
   /// Produce a user-readable information.
   markup::Document present() const;
 };
 
 // Try to infer structure of a documentation comment (e.g. line breaks).
+// FIXME: move to another file so CodeComplete doesn't depend on Hover.
 void parseDocumentation(llvm::StringRef Input, markup::Document &Output);
 
 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const HoverInfo::Param &);
 inline bool operator==(const HoverInfo::Param &LHS,
                        const HoverInfo::Param &RHS) {
   return std::tie(LHS.Type, LHS.Name, LHS.Default) ==
          std::tie(RHS.Type, RHS.Name, RHS.Default);
 }

clang-tools-extra/clangd/Hover.cpp

if (llvm::isDigit(Rest.front())) {
     llvm::StringRef AfterDigit = Rest.drop_while(llvm::isDigit);
     if (AfterDigit.startswith(".") || AfterDigit.startswith(")"))
       return true;
   }
   return false;
 }
 
 bool isHardLineBreakAfter(llvm::StringRef Line, llvm::StringRef Rest) {
+  // Should we also consider whether Line is short?
   return punctuationIndicatesLineBreak(Line) || isHardLineBreakIndicator(Rest);
 }
 
 void addLayoutInfo(const NamedDecl &ND, HoverInfo &HI) {
   const auto &Ctx = ND.getASTContext();
 
   if (auto *RD = llvm::dyn_cast<RecordDecl>(&ND)) {
     if (auto Size = Ctx.getTypeSizeInCharsIfKnown(RD->getTypeForDecl()))

clang-tools-extra/clangd/Protocol.h

struct ClientCapabilities {
   /// Client supports processing label offsets instead of a simple label string.
   /// textDocument.signatureHelp.signatureInformation.parameterInformation.labelOffsetSupport
   bool OffsetsInSignatureHelp = false;
 
   /// The supported set of CompletionItemKinds for textDocument/completion.
   /// textDocument.completion.completionItemKind.valueSet
   llvm::Optional<CompletionItemKindBitset> CompletionItemKinds;
 
+  /// The documentation format that should be used for textDocument/completion.
+  /// textDocument.completion.completionItem.documentationFormat
+  MarkupKind CompletionDocumentationFormat = MarkupKind::PlainText;
+
   /// Client supports CodeAction return value for textDocument/codeAction.
   /// textDocument.codeAction.codeActionLiteralSupport.
   bool CodeActionStructure = false;
 
   /// Client advertises support for the semanticTokens feature.
   /// We support the textDocument/semanticTokens request in any case.
   /// textDocument.semanticTokens
   bool SemanticTokens = false;
struct CompletionItem {
   /// the editor.
   CompletionItemKind kind = CompletionItemKind::Missing;
 
   /// A human-readable string with additional information about this item, like
   /// type or symbol information.
   std::string detail;
 
   /// A human-readable string that represents a doc-comment.
-  std::string documentation;
+  llvm::Optional<MarkupContent> documentation;
 
   /// A string that should be used when comparing this item with other items.
   /// When `falsy` the label is used.
   std::string sortText;
 
   /// A string that should be used when filtering a set of completion items.
   /// When `falsy` the label is used.
   std::string filterText;

clang-tools-extra/clangd/Protocol.cpp

if (auto *Diagnostics = TextDocument->getObject("publishDiagnostics")) {
         R.DiagnosticFixes = *CodeActions;
       if (auto RelatedInfo = Diagnostics->getBoolean("relatedInformation"))
         R.DiagnosticRelatedInformation = *RelatedInfo;
     }
     if (auto *Completion = TextDocument->getObject("completion")) {
       if (auto *Item = Completion->getObject("completionItem")) {
         if (auto SnippetSupport = Item->getBoolean("snippetSupport"))
           R.CompletionSnippets = *SnippetSupport;
+        if (auto DocumentationFormat = Item->getArray("documentationFormat")) {
+          for (const auto &Format : *DocumentationFormat) {
+            if (fromJSON(Format, R.CompletionDocumentationFormat))
+              break;
+          }
+        }
       }
       if (auto *ItemKind = Completion->getObject("completionItemKind")) {
         if (auto *ValueSet = ItemKind->get("valueSet")) {
           R.CompletionItemKinds.emplace();
           if (!fromJSON(*ValueSet, *R.CompletionItemKinds))
             return false;
         }
       }
       if (auto EditsNearCursor = Completion->getBoolean("editsNearCursor"))
         R.CompletionFixes = *EditsNearCursor;
     }
     if (auto *CodeAction = TextDocument->getObject("codeAction")) {
       if (CodeAction->getObject("codeActionLiteralSupport"))
         R.CodeActionStructure = true;
     }
     if (auto *DocumentSymbol = TextDocument->getObject("documentSymbol")) {
       if (auto HierarchicalSupport =
               DocumentSymbol->getBoolean("hierarchicalDocumentSymbolSupport"))
         R.HierarchicalDocumentSymbol = *HierarchicalSupport;
     }
     if (auto *Hover = TextDocument->getObject("hover")) {
       if (auto *ContentFormat = Hover->getArray("contentFormat")) {
         for (const auto &Format : *ContentFormat) {
-          MarkupKind K = MarkupKind::PlainText;
-          if (fromJSON(Format, K)) {
-            R.HoverContentFormat = K;
+          if (fromJSON(Format, R.HoverContentFormat))
             break;
-          }
-        }
-      }
-    }
     if (auto *Help = TextDocument->getObject("signatureHelp")) {
       R.HasSignatureHelp = true;
       if (auto *Info = Help->getObject("signatureInformation")) {
         if (auto *Parameter = Info->getObject("parameterInformation")) {
           if (auto OffsetSupport = Parameter->getBoolean("labelOffsetSupport"))
             R.OffsetsInSignatureHelp = *OffsetSupport;
         }
       }

 
 llvm::json::Value toJSON(const CompletionItem &CI) {
   assert(!CI.label.empty() && "completion item label is required");
   llvm::json::Object Result{{"label", CI.label}};
   if (CI.kind != CompletionItemKind::Missing)
     Result["kind"] = static_cast<int>(CI.kind);
   if (!CI.detail.empty())
     Result["detail"] = CI.detail;
-  if (!CI.documentation.empty())
+  if (CI.documentation)
     Result["documentation"] = CI.documentation;
   if (!CI.sortText.empty())
     Result["sortText"] = CI.sortText;
   if (!CI.filterText.empty())
     Result["filterText"] = CI.filterText;
   if (!CI.insertText.empty())
     Result["insertText"] = CI.insertText;
   if (CI.insertTextFormat != InsertTextFormat::Missing)

clang-tools-extra/clangd/unittests/CodeCompleteTests.cpp

 }
 MATCHER_P(Scope, S, "") { return arg.Scope == S; }
 MATCHER_P(Qualifier, Q, "") { return arg.RequiredQualifier == Q; }
 MATCHER_P(Labeled, Label, "") {
   return arg.RequiredQualifier + arg.Name + arg.Signature == Label;
 }
 MATCHER_P(SigHelpLabeled, Label, "") { return arg.label == Label; }
 MATCHER_P(Kind, K, "") { return arg.Kind == K; }
-MATCHER_P(Doc, D, "") { return arg.Documentation == D; }
+MATCHER_P(Doc, D, "") {
+  return arg.Documentation && arg.Documentation->asPlainText() == D;
+}
 MATCHER_P(ReturnType, D, "") { return arg.ReturnType == D; }
 MATCHER_P(HasInclude, IncludeHeader, "") {
   return !arg.Includes.empty() && arg.Includes[0].Header == IncludeHeader;
 }
 MATCHER_P(InsertInclude, IncludeHeader, "") {
   return !arg.Includes.empty() && arg.Includes[0].Header == IncludeHeader &&
          bool(arg.Includes[0].Insertion);
 }
 MATCHER(InsertInclude, "") {
   return !arg.Includes.empty() && bool(arg.Includes[0].Insertion);
 }
 MATCHER_P(SnippetSuffix, Text, "") { return arg.SnippetSuffix == Text; }
 MATCHER_P(Origin, OriginSet, "") { return arg.Origin == OriginSet; }
 MATCHER_P(Signature, S, "") { return arg.Signature == S; }
 
 // Shorthand for Contains(Named(Name)).
 Matcher<const std::vector<CodeCompletion> &> Has(std::string Name) {
   return Contains(Named(std::move(Name)));
 }
 Matcher<const std::vector<CodeCompletion> &> Has(std::string Name,
                                                  CompletionItemKind K) {
   return Contains(AllOf(Named(std::move(Name)), Kind(K)));
 }
-MATCHER(IsDocumented, "") { return !arg.Documentation.empty(); }
+MATCHER(IsDocumented, "") { return arg.Documentation.hasValue(); }
 MATCHER(Deprecated, "") { return arg.Deprecated; }
 
 std::unique_ptr<SymbolIndex> memIndex(std::vector<Symbol> Symbols) {
   SymbolSlab::Builder Slab;
   for (const auto &Sym : Symbols)
     Slab.insert(Sym);
   return MemIndex::build(std::move(Slab).build(), RefSlab(), RelationSlab());
 }
TEST(CompletionTest, Documentation) {
   auto Results = completions(
       R"cpp(
       // Non-doxygen comment.
       int foo();
       /// Doxygen comment.
       /// \param int a
       int bar(int a);
       /* Multi-line
          block comment
       */
       int baz();
 
       int x = ^
      )cpp");
   EXPECT_THAT(Results.Completions,
               Contains(AllOf(Named("foo"), Doc("Non-doxygen comment."))));
   EXPECT_THAT(
       Results.Completions,
       Contains(AllOf(Named("bar"), Doc("Doxygen comment.\n\\param int a"))));
   EXPECT_THAT(Results.Completions,
-              Contains(AllOf(Named("baz"), Doc("Multi-line\nblock comment"))));
+              Contains(AllOf(Named("baz"), Doc("Multi-line block comment"))));
 }
 
 TEST(CompletionTest, CommentsFromSystemHeaders) {
   MockFSProvider FS;
   MockCompilationDatabase CDB;
 
   auto Opts = ClangdServer::optsForTest();
   Opts.BuildDynamicSymbolIndex = true;
TEST(CompletionTest, OverloadBundling) {
   auto A =
       completions(Context + "int y = X().a^", {}, Opts).Completions.front();
   EXPECT_EQ(A.Name, "a");
   EXPECT_EQ(A.Signature, "(…)");
   EXPECT_EQ(A.BundleSize, 2u);
   EXPECT_EQ(A.Kind, CompletionItemKind::Method);
   EXPECT_EQ(A.ReturnType, "int"); // All overloads return int.
   // For now we just return one of the doc strings arbitrarily.
-  EXPECT_THAT(A.Documentation, AnyOf(HasSubstr("Overload with int"),
-                                     HasSubstr("Overload with bool")));
+  ASSERT_TRUE(A.Documentation);
+  EXPECT_THAT(
+      A.Documentation->asPlainText(),
+      AnyOf(HasSubstr("Overload with int"), HasSubstr("Overload with bool")));
   EXPECT_EQ(A.SnippetSuffix, "($0)");
 }
 
 TEST(CompletionTest, DocumentationFromChangedFileCrash) {
   MockFSProvider FS;
   auto FooH = testPath("foo.h");
   auto FooCpp = testPath("foo.cpp");
   FS.Files[FooH] = R"cpp(

 TEST(CompletionTest, Render) {
   CodeCompletion C;
   C.Name = "x";
   C.Signature = "(bool) const";
   C.SnippetSuffix = "(${0:bool})";
   C.ReturnType = "int";
   C.RequiredQualifier = "Foo::";
   C.Scope = "ns::Foo::";
-  C.Documentation = "This is x().";
+  C.Documentation.emplace();
+  C.Documentation->addParagraph().appendText("This is ").appendCode("x()");
   C.Includes.emplace_back();
   auto &Include = C.Includes.back();
   Include.Header = "\"foo.h\"";
   C.Kind = CompletionItemKind::Method;
   C.Score.Total = 1.0;
   C.Score.ExcludingName = .5;
   C.Origin = SymbolOrigin::AST | SymbolOrigin::Static;
 
   CodeCompleteOptions Opts;
   Opts.IncludeIndicator.Insert = "^";
   Opts.IncludeIndicator.NoInsert = "";
   Opts.EnableSnippets = false;
 
   auto R = C.render(Opts);
   EXPECT_EQ(R.label, "Foo::x(bool) const");
   EXPECT_EQ(R.insertText, "Foo::x");
   EXPECT_EQ(R.insertTextFormat, InsertTextFormat::PlainText);
   EXPECT_EQ(R.filterText, "x");
   EXPECT_EQ(R.detail, "int\n\"foo.h\"");
-  EXPECT_EQ(R.documentation, "This is x().");
+  EXPECT_EQ(R.documentation->value, "This is x()");
   EXPECT_THAT(R.additionalTextEdits, IsEmpty());
   EXPECT_EQ(R.sortText, sortText(1.0, "x"));
   EXPECT_FALSE(R.deprecated);
   EXPECT_EQ(R.score, .5f);
 
   Opts.EnableSnippets = true;
   R = C.render(Opts);
   EXPECT_EQ(R.insertText, "Foo::x(${0:bool})");
TEST(CompletionTest, Render) {
 
   C.BundleSize = 2;
   R = C.render(Opts);
   EXPECT_EQ(R.detail, "[2 overloads]\n\"foo.h\"");
 
   C.Deprecated = true;
   R = C.render(Opts);
   EXPECT_TRUE(R.deprecated);
+
+  Opts.DocumentationFormat = MarkupKind::Markdown;
+  R = C.render(Opts);
+  EXPECT_EQ(R.documentation->value, "This is `x()`");
 }
 
 TEST(CompletionTest, IgnoreRecoveryResults) {
   auto Results = completions(
       R"cpp(
           namespace ns { int NotRecovered() { return 0; } }
           void f() {
             // Sema enters recovery mode first and then normal mode.