[clang-doc] Fixes command line not appearing in html output

[PeterChou1]

Fixes #96819

currently the html output for clang-doc does not include block command comments this patch modifies the html generator to generate its output

[llvmbot]

@llvm/pr-subscribers-backend-nvptx
@llvm/pr-subscribers-mlir-gpu
@llvm/pr-subscribers-llvm-transforms
@llvm/pr-subscribers-flang-openmp
@llvm/pr-subscribers-mlir-arith
@llvm/pr-subscribers-llvm-analysis
@llvm/pr-subscribers-function-specialization
@llvm/pr-subscribers-github-workflow
@llvm/pr-subscribers-compiler-rt-sanitizer
@llvm/pr-subscribers-llvm-ir
@llvm/pr-subscribers-openacc
@llvm/pr-subscribers-mlir-vector
@llvm/pr-subscribers-mlir-sme
@llvm/pr-subscribers-llvm-support
@llvm/pr-subscribers-llvm-globalisel
@llvm/pr-subscribers-mlir-openacc
@llvm/pr-subscribers-backend-loongarch
@llvm/pr-subscribers-backend-directx
@llvm/pr-subscribers-llvm-regalloc
@llvm/pr-subscribers-flang-runtime
@llvm/pr-subscribers-debuginfo
@llvm/pr-subscribers-mlir-core
@llvm/pr-subscribers-backend-arm
@llvm/pr-subscribers-hlsl
@llvm/pr-subscribers-clang-static-analyzer-1
@llvm/pr-subscribers-pgo
@llvm/pr-subscribers-tools-llvm-exegesis
@llvm/pr-subscribers-backend-systemz
@llvm/pr-subscribers-backend-risc-v
@llvm/pr-subscribers-backend-x86
@llvm/pr-subscribers-backend-amdgpu
@llvm/pr-subscribers-libcxxabi

@llvm/pr-subscribers-clang-tools-extra

Author: None (PeterChou1)

Changes

Fixes #96819

currently the html output for clang-doc does not include block command comments this patch modifies the html generator to generate its output

---

Full diff: https://github.com/llvm/llvm-project/pull/101104.diff

2 Files Affected:

• (modified) clang-tools-extra/clang-doc/HTMLGenerator.cpp (+24-4)
• (modified) clang-tools-extra/test/clang-doc/basic-project.test (+70-16)

diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
index aef22453035c3..20999fff6a8c4 100644
--- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
@@ -352,8 +352,10 @@ genHTML(const EnumInfo &I, const ClangDocContext &CDCtx);
 static std::vector<std::unique_ptr<TagNode>>
 genHTML(const FunctionInfo &I, const ClangDocContext &CDCtx,
         StringRef ParentInfoDir);
+static std::unique_ptr<TagNode>
+genHTML(const std::vector<CommentInfo> &C);
 
-static std::vector<std::unique_ptr<TagNode>>
+    static std::vector<std::unique_ptr<TagNode>>
 genEnumsBlock(const std::vector<EnumInfo> &Enums,
               const ClangDocContext &CDCtx) {
   if (Enums.empty())
@@ -418,9 +420,13 @@ genRecordMembersBlock(const llvm::SmallVector<MemberTypeInfo, 4> &Members,
     if (Access != "")
       Access = Access + " ";
     auto LIBody = std::make_unique<TagNode>(HTMLTag::TAG_LI);
-    LIBody->Children.emplace_back(std::make_unique<TextNode>(Access));
-    LIBody->Children.emplace_back(genReference(M.Type, ParentInfoDir));
-    LIBody->Children.emplace_back(std::make_unique<TextNode>(" " + M.Name));
+    auto MemberDecl = std::make_unique<TagNode>(HTMLTag::TAG_LI);
+    MemberDecl->Children.emplace_back(std::make_unique<TextNode>(Access));
+    MemberDecl->Children.emplace_back(genReference(M.Type, ParentInfoDir));
+    MemberDecl->Children.emplace_back(std::make_unique<TextNode>(" " + M.Name));
+    if (!M.Description.empty())
+      LIBody->Children.emplace_back(genHTML(M.Description));
+    LIBody->Children.emplace_back(std::move(MemberDecl));
     ULBody->Children.emplace_back(std::move(LIBody));
   }
   return Out;
@@ -632,6 +638,20 @@ static std::unique_ptr<HTMLNode> genHTML(const CommentInfo &I) {
     return std::move(ParagraphComment);
   }
 
+  if (I.Kind == "BlockCommandComment") {
+    auto BlockComment = std::make_unique<TagNode>(HTMLTag::TAG_DIV);
+    auto Command = std::make_unique<TagNode>(HTMLTag::TAG_DIV, I.Name);
+    BlockComment->Children.emplace_back(std::move(Command));
+    for (const auto &Child : I.Children) {
+      std::unique_ptr<HTMLNode> Node = genHTML(*Child);
+      if (Node)
+        BlockComment->Children.emplace_back(std::move(Node));
+    }
+    if (BlockComment->Children.empty())
+      return nullptr;
+    return std::move(BlockComment);
+  }
+
   if (I.Kind == "TextComment") {
     if (I.Text == "")
       return nullptr;
diff --git a/clang-tools-extra/test/clang-doc/basic-project.test b/clang-tools-extra/test/clang-doc/basic-project.test
index 38569d824f1f0..c388b2c841898 100644
--- a/clang-tools-extra/test/clang-doc/basic-project.test
+++ b/clang-tools-extra/test/clang-doc/basic-project.test
@@ -59,32 +59,63 @@
 
 // HTML-SHAPE: <h1>class Shape</h1>
 // HTML-SHAPE: <p>Defined at line 8 of file {{.*}}Shape.h</p>
+// HTML-SHAPE: <div>brief</div>
+// HTML-SHAPE: <p> Abstract base class for shapes.</p>
 // HTML-SHAPE: <p> Provides a common interface for different types of shapes.</p>
 // HTML-SHAPE: <h2 id="Functions">Functions</h2>
 // HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">~Shape</h3>
 // HTML-SHAPE: <p>public void ~Shape()</p>
 // HTML-SHAPE: <p>Defined at line 13 of file {{.*}}Shape.h</p>
+// HTML-SHAPE: <div>brief</div>
+// HTML-SHAPE: <p> Virtual destructor.</p>
 // HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
 // HTML-SHAPE: <p>public double area()</p>
+// HTML-SHAPE: <div>brief</div>
+// HTML-SHAPE: <p> Calculates the area of the shape.</p>
 // HTML-SHAPE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
 // HTML-SHAPE: <p>public double perimeter()</p>
+// HTML-SHAPE: <div>brief</div>
+// HTML-SHAPE: <p> Calculates the perimeter of the shape.</p>
+// HTML-SHAPE: <div>return</div>
+// HTML-SHAPE: <p> double The perimeter of the shape.</p>
 
-// HTML-CALC:  <h1>class Calculator</h1>
-// HTML-CALC:  <p>Defined at line 8 of file {{.*}}Calculator.h</p>
-// HTML-CALC:  <p> Provides basic arithmetic operations.</p>
-// HTML-CALC:  <h2 id="Functions">Functions</h2>
-// HTML-CALC:  <h3 id="{{([0-9A-F]{40})}}">add</h3>
-// HTML-CALC:  <p>public int add(int a, int b)</p>
-// HTML-CALC:  <p>Defined at line 3 of file {{.*}}Calculator.cpp</p>
-// HTML-CALC:  <h3 id="{{([0-9A-F]{40})}}">subtract</h3>
-// HTML-CALC:  <p>public int subtract(int a, int b)</p>
-// HTML-CALC:  <p>Defined at line 7 of file {{.*}}Calculator.cpp</p>
-// HTML-CALC:  <h3 id="{{([0-9A-F]{40})}}">multiply</h3>
-// HTML-CALC:  <p>public int multiply(int a, int b)</p>
-// HTML-CALC:  <p>Defined at line 11 of file {{.*}}Calculator.cpp</p>
-// HTML-CALC:  <h3 id="{{([0-9A-F]{40})}}">divide</h3>
-// HTML-CALC:  <p>public double divide(int a, int b)</p>
-// HTML-CALC:  <p>Defined at line 15 of file {{.*}}Calculator.cpp</p>
+
+// HTML-CALC: <h1>class Calculator</h1>
+// HTML-CALC: <p>Defined at line 8 of file {{.*}}Calculator.h</p>
+// HTML-CALC: <div>brief</div>
+// HTML-CALC: <p> A simple calculator class.</p>
+// HTML-CALC: <p> Provides basic arithmetic operations.</p>
+// HTML-CALC: <h2 id="Functions">Functions</h2>
+// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">add</h3>
+// HTML-CALC: <p>public int add(int a, int b)</p>
+// HTML-CALC: <p>Defined at line 3 of file {{.*}}Calculator.cpp</p>
+// HTML-CALC: <div>brief</div>
+// HTML-CALC: <p> Adds two integers.</p>
+// HTML-CALC: <div>return</div>
+// HTML-CALC: <p> int The sum of a and b.</p>
+// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">subtract</h3>
+// HTML-CALC: <p>public int subtract(int a, int b)</p>
+// HTML-CALC: <p>Defined at line 7 of file {{.*}}Calculator.cpp</p>
+// HTML-CALC: <div>brief</div>
+// HTML-CALC: <p> Subtracts the second integer from the first.</p>
+// HTML-CALC: <div>return</div>
+// HTML-CALC: <p> int The result of a - b.</p>
+// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">multiply</h3>
+// HTML-CALC: <p>public int multiply(int a, int b)</p>
+// HTML-CALC: <p>Defined at line 11 of file {{.*}}Calculator.cpp</p>
+// HTML-CALC: <div>brief</div>
+// HTML-CALC: <p> Multiplies two integers.</p>
+// HTML-CALC: <div>return</div>
+// HTML-CALC: <p> int The product of a and b.</p>
+// HTML-CALC: <h3 id="{{([0-9A-F]{40})}}">divide</h3>
+// HTML-CALC: <p>public double divide(int a, int b)</p>
+// HTML-CALC: <p>Defined at line 15 of file {{.*}}Calculator.cpp</p>
+// HTML-CALC: <div>brief</div>
+// HTML-CALC: <p> Divides the first integer by the second.</p>
+// HTML-CALC: <div>return</div>
+// HTML-CALC: <p> double The result of a / b.</p>
+// HTML-CALC: <div>throw</div>
+// HTML-CALC: <p>if b is zero.</p>
 
 // HTML-RECTANGLE: <h1>class Rectangle</h1>
 // HTML-RECTANGLE: <p>Defined at line 10 of file {{.*}}Rectangle.h</p>
@@ -100,32 +131,55 @@
 // HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">Rectangle</h3>
 // HTML-RECTANGLE: <p>public void Rectangle(double width, double height)</p>
 // HTML-RECTANGLE: <p>Defined at line 3 of file {{.*}}Rectangle.cpp</p>
+// HTML-RECTANGLE: <div>brief</div>
+// HTML-RECTANGLE: <p> Constructs a new Rectangle object.</p>
 // HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
 // HTML-RECTANGLE: <p>public double area()</p>
 // HTML-RECTANGLE: <p>Defined at line 6 of file {{.*}}Rectangle.cpp</p>
+// HTML-RECTANGLE: <div>brief</div>
+// HTML-RECTANGLE: <p> Calculates the area of the rectangle.</p>
+// HTML-RECTANGLE: <div>return</div>
+// HTML-RECTANGLE: <p> double The area of the rectangle.</p>
 // HTML-RECTANGLE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
 // HTML-RECTANGLE: <p>public double perimeter()</p>
 // HTML-RECTANGLE: <p>Defined at line 10 of file {{.*}}Rectangle.cpp</p>
+// HTML-RECTANGLE: <div>brief</div>
+// HTML-RECTANGLE: <p> Calculates the perimeter of the rectangle.</p>
+// HTML-RECTANGLE: <div>return</div>
+// HTML-RECTANGLE: <p> double The perimeter of the rectangle.</p>
 
 // HTML-CIRCLE: <h1>class Circle</h1>
 // HTML-CIRCLE: <p>Defined at line 10 of file {{.*}}Circle.h</p>
+// HTML-CIRCLE: <div>brief</div>
+// HTML-CIRCLE: <p> Circle class derived from Shape.</p>
 // HTML-CIRCLE: <p> Represents a circle with a given radius.</p>
 // HTML-CIRCLE: <p>
 // HTML-CIRCLE:   Inherits from
 // HTML-CIRCLE:   <a href="Shape.html">Shape</a>
 // HTML-CIRCLE: </p>
 // HTML-CIRCLE: <h2 id="Members">Members</h2>
+// HTML-CIRCLE: <p> Radius of the circle.</p>
 // HTML-CIRCLE: <li>private double radius_</li>
 // HTML-CIRCLE: <h2 id="Functions">Functions</h2>
 // HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">Circle</h3>
 // HTML-CIRCLE: <p>public void Circle(double radius)</p>
 // HTML-CIRCLE: <p>Defined at line 3 of file {{.*}}Circle.cpp</p>
+// HTML-CIRCLE: <div>brief</div>
+// HTML-CIRCLE: <p> Constructs a new Circle object.</p>
 // HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">area</h3>
 // HTML-CIRCLE: <p>public double area()</p>
 // HTML-CIRCLE: <p>Defined at line 5 of file {{.*}}Circle.cpp</p>
+// HTML-CIRCLE: <div>brief</div>
+// HTML-CIRCLE: <p> Calculates the area of the circle.</p>
+// HTML-CIRCLE: <div>return</div>
+// HTML-CIRCLE: <p> double The area of the circle.</p>
 // HTML-CIRCLE: <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
 // HTML-CIRCLE: <p>public double perimeter()</p>
 // HTML-CIRCLE: <p>Defined at line 9 of file {{.*}}Circle.cpp</p>
+// HTML-CIRCLE: <div>brief</div>
+// HTML-CIRCLE: <p> Calculates the perimeter of the circle.</p>
+// HTML-CIRCLE: <div>return</div>
+// HTML-CIRCLE: <p> double The perimeter of the circle.</p>
 
 // MD-CALC: # class Calculator
 // MD-CALC: *Defined at .{{[\/]}}include{{[\/]}}Calculator.h#8*

[github-actions]

⚠️ C/C++ code formatter, clang-format found issues in your code. ⚠️

You can test this locally with the following command:

git-clang-format --diff 842a332f11f53c698fa0560505e533ecdca28876 4be343d24f64178648da43ba7c49d71266c62aa7 --extensions cpp -- clang-tools-extra/clang-doc/HTMLGenerator.cpp

View the diff from clang-format here.

diff --git a/clang-tools-extra/clang-doc/HTMLGenerator.cpp b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
index 20999fff6a..3607ae1fae 100644
--- a/clang-tools-extra/clang-doc/HTMLGenerator.cpp
+++ b/clang-tools-extra/clang-doc/HTMLGenerator.cpp
@@ -352,10 +352,9 @@ genHTML(const EnumInfo &I, const ClangDocContext &CDCtx);
 static std::vector<std::unique_ptr<TagNode>>
 genHTML(const FunctionInfo &I, const ClangDocContext &CDCtx,
         StringRef ParentInfoDir);
-static std::unique_ptr<TagNode>
-genHTML(const std::vector<CommentInfo> &C);
+static std::unique_ptr<TagNode> genHTML(const std::vector<CommentInfo> &C);
 
-    static std::vector<std::unique_ptr<TagNode>>
+static std::vector<std::unique_ptr<TagNode>>
 genEnumsBlock(const std::vector<EnumInfo> &Enums,
               const ClangDocContext &CDCtx) {
   if (Enums.empty())

[PeterChou1]

Ops please disregard this