Skip to content

Commit f361dd7

Browse files
evelez7evelez7
authored
[clang-doc] separate comments into categories (#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 548ca9e commit f361dd7

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)