Skip to content

Commit e3d56c0

Browse files
evelez7evelez7
committed
[clang-doc] separate comments into categories
Comment categories will allow better comment organization in HTML. Before, comments would just be serialized in whatever order they were written, so groups like params or notes wouldn't be in the same sections.
1 parent b36a2d4 commit e3d56c0

File tree

3 files changed

+63
-45
lines changed

3 files changed

+63
-45
lines changed

‎clang-tools-extra/clang-doc/JSONGenerator.cpp

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,21 @@ serializeLocation(const Location &Loc,
8383
return LocationObj;
8484
}
8585

86-
static json::Value serializeComment(const CommentInfo &I) {
86+
static void insertComment(Object &Description, json::Value &Comment,
87+
std::string Key) {
88+
auto *CommentArray = Description.getArray(Key);
89+
if (!CommentArray) {
90+
auto CommentsArray = json::Array();
91+
CommentsArray.push_back(Comment);
92+
Description[Key] = std::move(CommentsArray);
93+
Description["Has" + Key] = true;
94+
} else {
95+
CommentArray->push_back(Comment);
96+
Description[Key] = std::move(*CommentArray);
97+
}
98+
}
99+
100+
static Object serializeComment(const CommentInfo &I, Object &Description) {
87101
// taken from PR #142273
88102
Object Obj = Object();
89103

@@ -94,7 +108,7 @@ static json::Value serializeComment(const CommentInfo &I) {
94108
auto &CARef = *ChildArr.getAsArray();
95109
CARef.reserve(I.Children.size());
96110
for (const auto &C : I.Children)
97-
CARef.emplace_back(serializeComment(*C));
111+
CARef.emplace_back(serializeComment(*C, Description));
98112

99113
switch (I.Kind) {
100114
case CommentKind::CK_TextComment: {
@@ -106,6 +120,8 @@ static json::Value serializeComment(const CommentInfo &I) {
106120
Child.insert({"Command", I.Name});
107121
Child.insert({"Children", ChildArr});
108122
Obj.insert({commentKindToString(I.Kind), ChildVal});
123+
if (I.Name == "brief")
124+
insertComment(Description, ChildVal, "BriefComments");
109125
return Obj;
110126
}
111127

@@ -137,7 +153,10 @@ static json::Value serializeComment(const CommentInfo &I) {
137153
if (!I.CloseName.empty())
138154
Child.insert({"CloseName", I.CloseName});
139155
Child.insert({"Children", ChildArr});
140-
Obj.insert({commentKindToString(I.Kind), ChildVal});
156+
if (I.CloseName == "endcode")
157+
insertComment(Description, ChildVal, "CodeComments");
158+
else if (I.CloseName == "endverbatim")
159+
insertComment(Description, ChildVal, "VerbatimComments");
141160
return Obj;
142161
}
143162

@@ -210,12 +229,17 @@ serializeCommonAttributes(const Info &I, json::Object &Obj,
210229
}
211230

212231
if (!I.Description.empty()) {
213-
json::Value DescArray = json::Array();
214-
auto &DescArrayRef = *DescArray.getAsArray();
215-
DescArrayRef.reserve(I.Description.size());
216-
for (const auto &Comment : I.Description)
217-
DescArrayRef.push_back(serializeComment(Comment));
218-
Obj["Description"] = DescArray;
232+
Object Description = Object();
233+
// Skip straight to the FullComment's children
234+
auto &Comments = I.Description.at(0).Children;
235+
for (const auto &CommentInfo : Comments) {
236+
json::Value Comment = serializeComment(*CommentInfo, Description);
237+
// Paragraph comments might not be children
238+
if (auto *ParagraphComment =
239+
Comment.getAsObject()->get("ParagraphComment"))
240+
insertComment(Description, *ParagraphComment, "ParagraphComments");
241+
}
242+
Obj["Description"] = std::move(Description);
219243
}
220244

221245
// Namespaces aren't SymbolInfos, so they dont have a DefLoc

‎clang-tools-extra/test/clang-doc/json/class.cpp

Lines changed: 24 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -33,33 +33,30 @@ struct MyClass {
3333
};
3434

3535
// CHECK: {
36-
// CHECK-NEXT: "Description": [
37-
// CHECK-NEXT: {
38-
// CHECK-NEXT: "FullComment": {
39-
// CHECK-NEXT: "Children": [
40-
// CHECK-NEXT: {
41-
// CHECK-NEXT: "ParagraphComment": {
42-
// CHECK-NEXT: "Children": [
43-
// CHECK-NEXT: {
44-
// CHECK-NEXT: "TextComment": " This is a nice class."
45-
// CHECK-NEXT: },
46-
// CHECK-NEXT: {
47-
// CHECK-NEXT: "TextComment": " It has some nice methods and fields."
48-
// CHECK-NEXT: },
49-
// CHECK-NEXT: {
50-
// CHECK-NEXT: "TextComment": ""
51-
// CHECK-NEXT: }
52-
// CHECK-NEXT: ]
53-
// CHECK: {
54-
// CHECK-NEXT: "BlockCommandComment": {
55-
// CHECK-NEXT: "Children": [
56-
// CHECK-NEXT: {
57-
// CHECK-NEXT: "ParagraphComment": {
58-
// CHECK-NEXT: "Children": [
59-
// CHECK-NEXT: {
60-
// CHECK-NEXT: "TextComment": " This is a brief description."
61-
// CHECK-NEXT: }
62-
// CHECK: "Command": "brief"
36+
// CHECK-NEXT: "Description": {
37+
// CHECK-NEXT: "BriefComments": [
38+
// CHECK-NEXT: {
39+
// CHECK-NEXT: "Children": [
40+
// CHECK-NEXT: {
41+
// CHECK-NEXT: "ParagraphComment": {
42+
// CHECK-NEXT: "Children": [
43+
// CHECK-NEXT: {
44+
// CHECK-NEXT: "TextComment": " This is a brief description."
45+
// CHECK: "Command": "brief"
46+
// CHECK: "HasBriefComments": true,
47+
// CHECK-NEXT: "HasParagraphComments": true,
48+
// CHECK-NEXT: "ParagraphComments": [
49+
// CHECK-NEXT: {
50+
// CHECK-NEXT: "Children": [
51+
// CHECK-NEXT: {
52+
// CHECK-NEXT: "TextComment": " This is a nice class."
53+
// CHECK-NEXT: },
54+
// CHECK-NEXT: {
55+
// CHECK-NEXT: "TextComment": " It has some nice methods and fields."
56+
// CHECK-NEXT: },
57+
// CHECK-NEXT: {
58+
// CHECK-NEXT: "TextComment": ""
59+
// CHECK-NEXT: }
6360
// CHECK: "DocumentationFileName": "_ZTV7MyClass",
6461
// CHECK: "Enums": [
6562
// CHECK-NEXT: {

‎clang-tools-extra/test/clang-doc/json/concept.cpp

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,13 @@ concept Incrementable = requires(T x) {
1313
// CHECK-NEXT: "Concepts": [
1414
// CHECK-NEXT: {
1515
// CHECK-NEXT: "ConstraintExpression": "requires (T x) { ++x; x++; }",
16-
// CHECK-NEXT: "Description": [
16+
// CHECK-NEXT: "Description": {
17+
// CHECK-NEXT: "HasParagraphComments": true,
18+
// CHECK-NEXT: "ParagraphComments": [
1719
// CHECK-NEXT: {
18-
// CHECK-NEXT: "FullComment": {
19-
// CHECK-NEXT: "Children": [
20-
// CHECK-NEXT: {
21-
// CHECK-NEXT: "ParagraphComment": {
22-
// CHECK-NEXT: "Children": [
23-
// CHECK-NEXT: {
24-
// CHECK-NEXT: "TextComment": " Requires that T suports post and pre-incrementing."
25-
// CHECK: ],
20+
// CHECK-NEXT: "Children": [
21+
// CHECK-NEXT: {
22+
// CHECK-NEXT: "TextComment": " Requires that T suports post and pre-incrementing."
2623
// CHECK: "End": true,
2724
// CHECK-NEXT: "InfoType": "concept",
2825
// CHECK-NEXT: "IsType": true,

0 commit comments

Comments
 (0)