Skip to content

Commit b2dd80d

Browse files
evelez7mahesh-attarde
evelez7
authored and
mahesh-attarde
committed
[clang-doc] separate comments into categories (llvm#149590)
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 95e781d commit b2dd80d

File tree

3 files changed

+67
-45
lines changed

3 files changed

+67
-45
lines changed

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

Lines changed: 37 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+
StringRef Key) {
88+
auto DescriptionIt = Description.find(Key);
89+
90+
if (DescriptionIt == Description.end()) {
91+
auto CommentsArray = json::Array();
92+
CommentsArray.push_back(Comment);
93+
Description[Key] = std::move(CommentsArray);
94+
Description["Has" + Key.str()] = true;
95+
} else {
96+
DescriptionIt->getSecond().getAsArray()->push_back(Comment);
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: {
@@ -104,8 +118,13 @@ static json::Value serializeComment(const CommentInfo &I) {
104118

105119
case CommentKind::CK_BlockCommandComment: {
106120
Child.insert({"Command", I.Name});
121+
// TODO: The "Children" level of nesting isn't needed for comments that
122+
// don't hold additional information at the top level. BriefComments can
123+
// just be an array of ParagraphComments.
107124
Child.insert({"Children", ChildArr});
108125
Obj.insert({commentKindToString(I.Kind), ChildVal});
126+
if (I.Name == "brief")
127+
insertComment(Description, ChildVal, "BriefComments");
109128
return Obj;
110129
}
111130

@@ -137,7 +156,10 @@ static json::Value serializeComment(const CommentInfo &I) {
137156
if (!I.CloseName.empty())
138157
Child.insert({"CloseName", I.CloseName});
139158
Child.insert({"Children", ChildArr});
140-
Obj.insert({commentKindToString(I.Kind), ChildVal});
159+
if (I.CloseName == "endcode")
160+
insertComment(Description, ChildVal, "CodeComments");
161+
else if (I.CloseName == "endverbatim")
162+
insertComment(Description, ChildVal, "VerbatimComments");
141163
return Obj;
142164
}
143165

@@ -210,12 +232,18 @@ serializeCommonAttributes(const Info &I, json::Object &Obj,
210232
}
211233

212234
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;
235+
Object Description = Object();
236+
// Skip straight to the FullComment's children
237+
auto &Comments = I.Description.at(0).Children;
238+
for (const auto &CommentInfo : Comments) {
239+
json::Value Comment = serializeComment(*CommentInfo, Description);
240+
// if a ParagraphComment is returned, then it is a top-level comment that
241+
// needs to be inserted manually.
242+
if (auto *ParagraphComment =
243+
Comment.getAsObject()->get("ParagraphComment"))
244+
insertComment(Description, *ParagraphComment, "ParagraphComments");
245+
}
246+
Obj["Description"] = std::move(Description);
219247
}
220248

221249
// 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)