itroduce brief section, use h3 headings for all section, remove rulers for highlighted commands

Author: tcottin

clang-tools-extra/clangd/Hover.cpp

@@ -1535,6 +1535,12 @@ markup::Document HoverInfo::presentDoxygen() const {
   SymbolDocCommentVisitor SymbolDoc(Documentation, CommentOpts);
 
   if (SymbolDoc.hasBriefCommand()) {
+    if (Kind != index::SymbolKind::Parameter &&
+        Kind != index::SymbolKind::TemplateTypeParm)
+      // Only add a "Brief" heading if we are not documenting a parameter.
+      // Parameters only have a brief section and adding the brief header would
+      // be redundant.
+      Output.addHeading(3).appendText("Brief");
     SymbolDoc.briefToMarkup(Output.addParagraph());
     Output.addRuler();
   }
@@ -1548,7 +1554,7 @@ markup::Document HoverInfo::presentDoxygen() const {
   // Returns
   // `type` - description
   if (TemplateParameters && !TemplateParameters->empty()) {
-    Output.addParagraph().appendBoldText("Template Parameters:");
+    Output.addHeading(3).appendText("Template Parameters");
     markup::BulletList &L = Output.addBulletList();
     for (const auto &Param : *TemplateParameters) {
       markup::Paragraph &P = L.addItem().addParagraph();
@@ -1562,7 +1568,7 @@ markup::Document HoverInfo::presentDoxygen() const {
   }
 
   if (Parameters && !Parameters->empty()) {
-    Output.addParagraph().appendBoldText("Parameters:");
+    Output.addHeading(3).appendText("Parameters");
     markup::BulletList &L = Output.addBulletList();
     for (const auto &Param : *Parameters) {
       markup::Paragraph &P = L.addItem().addParagraph();
@@ -1581,7 +1587,7 @@ markup::Document HoverInfo::presentDoxygen() const {
   if (ReturnType &&
       ((ReturnType->Type != "void" && !ReturnType->AKA.has_value()) ||
        (ReturnType->AKA.has_value() && ReturnType->AKA != "void"))) {
-    Output.addParagraph().appendBoldText("Returns:");
+    Output.addHeading(3).appendText("Returns");
     markup::Paragraph &P = Output.addParagraph();
     P.appendCode(llvm::to_string(*ReturnType));
 
@@ -1595,7 +1601,7 @@ markup::Document HoverInfo::presentDoxygen() const {
   }
 
   if (SymbolDoc.hasDetailedDoc()) {
-    Output.addParagraph().appendBoldText("Details:");
+    Output.addHeading(3).appendText("Details");
     SymbolDoc.detailedDocToMarkup(Output);
   }
 

clang-tools-extra/clangd/SymbolDocumentation.cpp

@@ -339,14 +339,12 @@ class BlockCommentToMarkupDocument
   /// Emphasize the given command in a paragraph.
   /// Uses the command name with the first letter capitalized as the heading.
   void commandToHeadedParagraph(const comments::BlockCommandComment *B) {
-    Out.addRuler();
     auto &P = Out.addParagraph();
     std::string Heading = B->getCommandName(Traits).slice(0, 1).upper() +
                           B->getCommandName(Traits).drop_front().str();
     P.appendBoldText(Heading + ":");
     P.appendText("  \n");
     ParagraphToMarkupDocument(P, Traits).visit(B->getParagraph());
-    Out.addRuler();
   }
 };
 

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

@@ -3457,10 +3457,12 @@ template <typename T, typename C = bool> class Foo {}
 ```
 
 ---
+### Brief
+
 documentation
 
 ---
-**Template Parameters:**
+### Template Parameters
 
 - `typename T`
 - `typename C = bool`
@@ -3506,15 +3508,15 @@ ret_type foo(params) {}
 ```
 
 ---
-**Parameters:**
+### Parameters
 
 - 
 - `type (aka can_type)`
 - `type foo (aka can_type)`
 - `type foo = default (aka can_type)`
 
 ---
-**Returns:**
+### Returns
 
 `ret_type (aka can_ret_type)`)",
       },
@@ -3649,7 +3651,7 @@ protected: size_t method()
 ```
 
 ---
-**Returns:**
+### Returns
 
 `size_t (aka unsigned long)`)",
       },
@@ -3688,7 +3690,7 @@ public: cls(int a, int b = 5)
 ```
 
 ---
-**Parameters:**
+### Parameters
 
 - `int a`
 - `int b = 5`)",
@@ -4001,10 +4003,12 @@ void foo()
 ```
 
 ---
+### Brief
+
 brief doc
 
 ---
-**Details:**
+### Details
 
 longer doc)"},
       {[](HoverInfo &HI) {
@@ -4036,15 +4040,17 @@ int foo()
 ```
 
 ---
+### Brief
+
 brief doc
 
 ---
-**Returns:**
+### Returns
 
 `int`
 
 ---
-**Details:**
+### Details
 
 longer doc)"},
       {[](HoverInfo &HI) {
@@ -4105,38 +4111,36 @@ int foo(int a)
 ```
 
 ---
+### Brief
+
 brief doc
 
 ---
-**Parameters:**
+### Parameters
 
 - `int a` - this is a param
 
 ---
-**Returns:**
+### Returns
 
 `int` - it returns something
 
 - `0` - if successful
 - `1` - if failed
 
 ---
-**Details:**
+### Details
 
 longer doc
 
----
 **Note:**  
 this is a note
 
----
 As you see, notes are "inlined".
 
----
 **Warning:**  
 this is a warning
 
----
 As well as warnings)"},
       {[](HoverInfo &HI) {
          HI.Kind = index::SymbolKind::Function;
@@ -4179,20 +4183,22 @@ int foo(int a)
 ```
 
 ---
+### Brief
+
 brief doc
 
 ---
-**Parameters:**
+### Parameters
 
 - `int a` - this is a param
 
 ---
-**Returns:**
+### Returns
 
 `int` - it returns something
 
 ---
-**Details:**
+### Details
 
 longer doc)"},
   };

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

@@ -218,19 +218,15 @@ Paragraph 1
 Paragraph 2)",
        R"(Paragraph 1
 
----
 \*\*Note:\*\*  
 This is a note
 
----
 Paragraph 2)",
        R"(Paragraph 1
 
----
 **Note:**  
 This is a note
 
----
 Paragraph 2)",
        R"(Paragraph 1
 
@@ -253,19 +249,15 @@ Paragraph 1
 Paragraph 2)",
        R"(Paragraph 1
 
----
 \*\*Warning:\*\*  
 This is a warning
 
----
 Paragraph 2)",
        R"(Paragraph 1
 
----
 **Warning:**  
 This is a warning
 
----
 Paragraph 2)",
        R"(Paragraph 1
 
@@ -281,12 +273,10 @@ Another paragraph)",
        R"(\*\*Note:\*\*  
 this is not treated as brief
 
----
 Another paragraph)",
        R"(**Note:**  
 this is not treated as brief
 
----
 Another paragraph)",
        R"(**Note:**
 this is not treated as brief
@@ -625,7 +615,6 @@ int function() { return 0; }
        R"(\*\*Note:\*\*  
 Show that code blocks are correctly separated
 
----
 ```
 /// Without the markdown preprocessing, this line and the line above would be part of the @note paragraph.
 
@@ -636,7 +625,6 @@ int function() { return 0; }
        R"(**Note:**  
 Show that code blocks are correctly separated
 
----
 ```
 /// Without the markdown preprocessing, this line and the line above would be part of the @note paragraph.
 
@@ -663,7 +651,6 @@ int function() { return 0; }
        R"(\*\*Note:\*\*  
 Show that code blocks are correctly separated
 
----
 ```
 /// Without the markdown preprocessing, this line and the line above would be part of the @note paragraph.
 
@@ -674,7 +661,6 @@ int function() { return 0; }
        R"(**Note:**  
 Show that code blocks are correctly separated
 
----
 ```
 /// Without the markdown preprocessing, this line and the line above would be part of the @note paragraph.