Skip to content

[clang-doc] add support for block commands in clang-doc html output #101108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Aug 20, 2024
Merged

[clang-doc] add support for block commands in clang-doc html output #101108

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
8d054ac
[clang-doc] add support for block commands
PeterChou1 Jul 30, 2024
c3845b9
[clang-doc] modify test
PeterChou1 Jul 30, 2024
e4c3554
[clang-doc] modify test
PeterChou1 Jul 30, 2024
eb865bd
[clang-doc] fix formatting
PeterChou1 Jul 30, 2024
bb95de4
[clang-doc] modify deleted newlines
PeterChou1 Jul 31, 2024
ae44501
[clang-doc] construct in place
PeterChou1 Jul 31, 2024
75907e9
Merge branch 'main' into clang-doc-fix-cmd-description
PeterChou1 Aug 12, 2024
1dec454
[clang-doc] fix test
PeterChou1 Aug 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion clang-tools-extra/clang-doc/HTMLGenerator.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -624,7 +624,7 @@ static std::unique_ptr<HTMLNode> genHTML(const CommentInfo &I) {
}
return std::move(FullComment);
}

if (I.Kind == "ParagraphComment") {
auto ParagraphComment = std::make_unique<TagNode>(HTMLTag::TAG_P);
for (const auto &Child : I.Children) {
Expand All @@ -637,6 +637,19 @@ 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);
BlockComment->Children.emplace_back(
std::make_unique<TagNode>(HTMLTag::TAG_DIV, I.Name));
for (const auto &Child : I.Children) {
std::unique_ptr<HTMLNode> Node = genHTML(*Child);
if (Node)
BlockComment->Children.emplace_back(std::move(Node));
Comment on lines +645 to +647
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
std::unique_ptr<HTMLNode> Node = genHTML(*Child);
if (Node)
BlockComment->Children.emplace_back(std::move(Node));
if(std::unique_ptr<HTMLNode> Node = genHTML(*Child))
BlockComment->Children.emplace_back(std::move(Node));

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh, you may also be able to remove the surrounding braces, I think.

}
if (BlockComment->Children.empty())
return nullptr;
return std::move(BlockComment);
}
if (I.Kind == "TextComment") {
if (I.Text == "")
return nullptr;
Expand Down
84 changes: 68 additions & 16 deletions clang-tools-extra/test/clang-doc/basic-project.test
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,32 +56,62 @@

// 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})}}">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-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>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: extra newline

// 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>
Expand All @@ -99,15 +129,27 @@
// 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
Expand All @@ -120,12 +162,22 @@
// 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*
Expand Down
Loading