[clangd] Render header of hover card as a heading

[merge_guards_bot]

Unit tests: pass. 61781 tests passed, 0 failed and 780 were skipped.

clang-tidy: unknown.

clang-format: pass.

Build artifacts: diff.json, clang-format.patch, CMakeCache.txt, console-log.txt, test-results.xml

clang-tools-extra/clangd/FormattedString.h

 //===--- FormattedString.h ----------------------------------*- C++-*------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
 // A simple intermediate representation of formatted text that could be
 // converted to plaintext or markdown.
 //
 //===----------------------------------------------------------------------===//
 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_FORMATTEDSTRING_H
 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_FORMATTEDSTRING_H
 
 #include "llvm/Support/raw_ostream.h"
+#include <cstddef>
 #include <memory>
 #include <string>
 #include <vector>
 
 namespace clang {
 namespace clangd {
 namespace markup {
 

 public:
   /// Adds a semantical block that will be separate from others.
   Paragraph &addParagraph();
   /// Inserts a vertical space into the document.
   void addSpacer();
   /// 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
+  /// Level many '#'s in markdown.
+  Paragraph &addHeading(size_t Level);
 
   BulletList &addBulletList();
 
   /// Doesn't contain any trailing newlines.
   std::string asMarkdown() const;
   /// Doesn't contain any trailing newlines.
   std::string asPlainText() const;
 
 private:
   std::vector<std::unique_ptr<Block>> Children;
 };
 } // namespace markup
 } // namespace clangd
 } // namespace clang
 
 #endif

clang-tools-extra/clangd/FormattedString.cpp

std::string indentLines(llvm::StringRef Input) {
   IndentedR.reserve(Input.size() + Input.count('\n') * 2);
   for (char C : Input) {
     IndentedR += C;
     if (C == '\n')
       IndentedR.append("  ");
   }
   return IndentedR;
 }
+
+class Heading : public Paragraph {
+public:
+  Heading(size_t Level) : Level(Level) {}
+  void renderMarkdown(llvm::raw_ostream &OS) const override {
+    OS << std::string(Level, '#') << ' ';
+    Paragraph::renderMarkdown(OS);
+  }
+
+private:
+  size_t Level;
+};
+
 } // namespace
 
 std::string Block::asMarkdown() const {
   std::string R;
   llvm::raw_string_ostream OS(R);
   renderMarkdown(OS);
   return llvm::StringRef(OS.str()).trim().str();
 }

 std::string Document::asPlainText() const {
   return renderBlocks(Children, &Block::renderPlainText);
 }
 
 BulletList &Document::addBulletList() {
   Children.emplace_back(std::make_unique<BulletList>());
   return *static_cast<BulletList *>(Children.back().get());
 }
+
+Paragraph &Document::addHeading(size_t Level) {
+  assert(Level > 0);
+  Children.emplace_back(std::make_unique<Heading>(Level));
+  return *static_cast<Paragraph *>(Children.back().get());
+}
 } // namespace markup
 } // namespace clangd
 } // namespace clang

clang-tools-extra/clangd/Hover.cpp

 markup::Document HoverInfo::present() const {
   markup::Document Output;
   // Header contains a text of the form:
   // variable `var` : `int`
   //
   // class `X`
   //
   // function `foo` → `int`
-  markup::Paragraph &Header = Output.addParagraph();
+  // Note that we are making use of a level-3 heading because VSCode renders
+  // level 1 and 2 headers in a huge font, see
+  // https://github.com/microsoft/vscode/issues/88417 for details.
+  markup::Paragraph &Header = Output.addHeading(3);
   Header.appendText(index::getSymbolKindString(Kind));
   assert(!Name.empty() && "hover triggered on a nameless symbol");
   Header.appendCode(Name);
   if (ReturnType) {
     Header.appendText("→");
     Header.appendCode(*ReturnType);
   } else if (Type) {
     Header.appendText(":");

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

TEST(Document, Spacer) {
   Document D;
   D.addParagraph().appendText("foo");
   D.addSpacer();
   D.addParagraph().appendText("bar");
   EXPECT_EQ(D.asMarkdown(), "foo  \n\nbar");
   EXPECT_EQ(D.asPlainText(), "foo\n\nbar");
 }
 
+TEST(Document, Heading) {
+  Document D;
+  D.addHeading(1).appendText("foo");
+  D.addHeading(2).appendText("bar");
+  D.addParagraph().appendText("baz");
+  EXPECT_EQ(D.asMarkdown(), "# foo  \n## bar  \nbaz");
+  EXPECT_EQ(D.asPlainText(), "foo\nbar\nbaz");
+}
+
 TEST(CodeBlock, Render) {
   Document D;
   // Code blocks preserves any extra spaces.
   D.addCodeBlock("foo\n  bar\n  baz");
 
   llvm::StringRef ExpectedMarkdown =
       R"md(```cpp
 foo

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

TEST(Hover, DocsFromMostSpecial) {
   for (auto Comment : {"doc1", "doc2", "doc3"}) {
     for (const auto &P : T.points(Comment)) {
       auto H = getHover(AST, P, format::getLLVMStyle(), nullptr);
       ASSERT_TRUE(H);
       EXPECT_EQ(H->Documentation, Comment);
     }
   }
 }
+
 TEST(Hover, Present) {
   struct {
     const std::function<void(HoverInfo &)> Builder;
     llvm::StringRef ExpectedRender;
   } Cases[] = {
       {
           [](HoverInfo &HI) {
             HI.Kind = index::SymbolKind::Unknown;
def)",
 
   for (const auto &C : Cases) {
     HoverInfo HI;
     C.Builder(HI);
     EXPECT_EQ(HI.present().asPlainText(), C.ExpectedRender);
   }
 }
 
+// This is a separate test as headings don't create any differences in plaintext
+// mode.
+TEST(Hover, PresentHeadings) {
+  HoverInfo HI;
+  HI.Kind = index::SymbolKind::Variable;
+  HI.Name = "foo";
+  HI.Type = "type";
+
+  EXPECT_EQ(HI.present().asMarkdown(), "### variable `foo` \\: `type`");
+}
+
 } // namespace
 } // namespace clangd
 } // namespace clang