Skip to content

Commit 58a8e1e

Browse files
evelez7evelez7
committed
Address review feedback, handle extraction better
1 parent 1c9368e commit 58a8e1e

File tree

3 files changed

+44
-103
lines changed

3 files changed

+44
-103
lines changed

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

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,24 @@ serializeLocation(const Location &Loc,
8484
return LocationObj;
8585
}
8686

87+
/// Insert comments into a key in the Description object.
88+
///
89+
/// \param Comment Either an Object or Array, depending on the comment type
90+
/// \param Key The type (Brief, Code, etc.) of comment to be inserted
8791
static void insertComment(Object &Description, json::Value &Comment,
8892
StringRef Key) {
93+
// The comment has a Children array for the actual text, with meta attributes
94+
// alongside it in the Object.
95+
if (auto *Obj = Comment.getAsObject()) {
96+
if (auto *Children = Obj->getArray("Children");
97+
!Children || Children->empty())
98+
return;
99+
}
100+
// The comment is just an array of text comments.
101+
else if (auto *Array = Comment.getAsArray(); !Array || Array->empty()) {
102+
return;
103+
}
104+
89105
auto DescriptionIt = Description.find(Key);
90106

91107
if (DescriptionIt == Description.end()) {
@@ -98,10 +114,31 @@ static void insertComment(Object &Description, json::Value &Comment,
98114
}
99115
}
100116

117+
/// Takes the nested "Children" array from a comment Object.
118+
///
119+
/// \return a json::Array of comments, possible json::Value::Kind::Null
101120
static json::Value extractTextComments(Object *ParagraphComment) {
102121
if (!ParagraphComment)
103-
return json::Object();
104-
return *ParagraphComment->get("Children");
122+
return json::Value(nullptr);
123+
json::Value *Children = ParagraphComment->get("Children");
124+
if (!Children)
125+
return json::Value(nullptr);
126+
auto ChildrenArray = *Children->getAsArray();
127+
auto ChildrenIt = ChildrenArray.begin();
128+
while (ChildrenIt != ChildrenArray.end()) {
129+
auto *ChildObj = ChildrenIt->getAsObject();
130+
if (!ChildObj) {
131+
++ChildrenIt;
132+
continue;
133+
}
134+
auto TextComment = ChildObj->getString("TextComment");
135+
if (!TextComment || TextComment->empty()) {
136+
ChildrenIt = ChildrenArray.erase(ChildrenIt);
137+
continue;
138+
}
139+
++ChildrenIt;
140+
}
141+
return ChildrenArray;
105142
}
106143

107144
static json::Value extractVerbatimComments(json::Array VerbatimLines) {
@@ -131,7 +168,8 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
131168

132169
switch (I.Kind) {
133170
case CommentKind::CK_TextComment: {
134-
Obj.insert({commentKindToString(I.Kind), I.Text});
171+
if (!I.Text.empty())
172+
Obj.insert({commentKindToString(I.Kind), I.Text});
135173
return Obj;
136174
}
137175

@@ -265,6 +303,9 @@ serializeCommonAttributes(const Info &I, json::Object &Obj,
265303
if (auto *ParagraphComment = Comment.getAsObject();
266304
ParagraphComment->get("ParagraphComment")) {
267305
auto TextCommentsArray = extractTextComments(ParagraphComment);
306+
if (TextCommentsArray.kind() == json::Value::Null ||
307+
TextCommentsArray.getAsArray()->empty())
308+
continue;
268309
insertComment(Description, TextCommentsArray, "ParagraphComments");
269310
}
270311
}

‎clang-tools-extra/test/clang-doc/basic-project.mustache.test‎

Lines changed: 0 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,6 @@ HTML-SHAPE: <div>
6565
HTML-SHAPE: <p> Abstract base class for shapes.</p>
6666
HTML-SHAPE: </div>
6767
HTML-SHAPE: <div>
68-
HTML-SHAPE: <p></p>
69-
HTML-SHAPE: </div>
70-
HTML-SHAPE: <div>
7168
HTML-SHAPE: <p> Provides a common interface for different types of shapes.</p>
7269
HTML-SHAPE: </div>
7370
HTML-SHAPE: </div>
@@ -83,12 +80,6 @@ HTML-SHAPE: <div>
8380
HTML-SHAPE: <div>
8481
HTML-SHAPE: <p> Calculates the area of the shape.</p>
8582
HTML-SHAPE: </div>
86-
HTML-SHAPE: <div>
87-
HTML-SHAPE: <p></p>
88-
HTML-SHAPE: </div>
89-
HTML-SHAPE: <div>
90-
HTML-SHAPE: <p></p>
91-
HTML-SHAPE: </div>
9283
HTML-SHAPE: <h3>Returns</h3>
9384
HTML-SHAPE: <p> double The area of the shape.</p>
9485
HTML-SHAPE: </div>
@@ -101,12 +92,6 @@ HTML-SHAPE: <div>
10192
HTML-SHAPE: <div>
10293
HTML-SHAPE: <p> Calculates the perimeter of the shape.</p>
10394
HTML-SHAPE: </div>
104-
HTML-SHAPE: <div>
105-
HTML-SHAPE: <p></p>
106-
HTML-SHAPE: </div>
107-
HTML-SHAPE: <div>
108-
HTML-SHAPE: <p></p>
109-
HTML-SHAPE: </div>
11095
HTML-SHAPE: <h3>Returns</h3>
11196
HTML-SHAPE: <p> double The perimeter of the shape.</p>
11297
HTML-SHAPE: </div>
@@ -119,9 +104,6 @@ HTML-SHAPE: <div>
119104
HTML-SHAPE: <div>
120105
HTML-SHAPE: <p> Virtual destructor.</p>
121106
HTML-SHAPE: </div>
122-
HTML-SHAPE: <div>
123-
HTML-SHAPE: <p></p>
124-
HTML-SHAPE: </div>
125107
HTML-SHAPE: </div>
126108
HTML-SHAPE: </div>
127109
HTML-SHAPE: </div>
@@ -210,9 +192,6 @@ HTML-CALC: <div>
210192
HTML-CALC: <p> A simple calculator class.</p>
211193
HTML-CALC: </div>
212194
HTML-CALC: <div>
213-
HTML-CALC: <p></p>
214-
HTML-CALC: </div>
215-
HTML-CALC: <div>
216195
HTML-CALC: <p> Provides basic arithmetic operations.</p>
217196
HTML-CALC: </div>
218197
HTML-CALC: </div>
@@ -239,12 +218,6 @@ HTML-CALC: <div>
239218
HTML-CALC: <div>
240219
HTML-CALC: <p> Adds two integers.</p>
241220
HTML-CALC: </div>
242-
HTML-CALC: <div>
243-
HTML-CALC: <p></p>
244-
HTML-CALC: </div>
245-
HTML-CALC: <div>
246-
HTML-CALC: <p></p>
247-
HTML-CALC: </div>
248221
HTML-CALC: <h3>Parameters</h3>
249222
HTML-CALC: <div>
250223
HTML-CALC: <b>a</b> First integer.
@@ -264,12 +237,6 @@ HTML-CALC: <div>
264237
HTML-CALC: <div>
265238
HTML-CALC: <p> Subtracts the second integer from the first.</p>
266239
HTML-CALC: </div>
267-
HTML-CALC: <div>
268-
HTML-CALC: <p></p>
269-
HTML-CALC: </div>
270-
HTML-CALC: <div>
271-
HTML-CALC: <p></p>
272-
HTML-CALC: </div>
273240
HTML-CALC: <h3>Parameters</h3>
274241
HTML-CALC: <div>
275242
HTML-CALC: <b>a</b> First integer.
@@ -289,12 +256,6 @@ HTML-CALC: <div>
289256
HTML-CALC: <div>
290257
HTML-CALC: <p> Multiplies two integers.</p>
291258
HTML-CALC: </div>
292-
HTML-CALC: <div>
293-
HTML-CALC: <p></p>
294-
HTML-CALC: </div>
295-
HTML-CALC: <div>
296-
HTML-CALC: <p></p>
297-
HTML-CALC: </div>
298259
HTML-CALC: <h3>Parameters</h3>
299260
HTML-CALC: <div>
300261
HTML-CALC: <b>a</b> First integer.
@@ -314,12 +275,6 @@ HTML-CALC: <div>
314275
HTML-CALC: <div>
315276
HTML-CALC: <p> Divides the first integer by the second.</p>
316277
HTML-CALC: </div>
317-
HTML-CALC: <div>
318-
HTML-CALC: <p></p>
319-
HTML-CALC: </div>
320-
HTML-CALC: <div>
321-
HTML-CALC: <p></p>
322-
HTML-CALC: </div>
323278
HTML-CALC: <h3>Parameters</h3>
324279
HTML-CALC: <div>
325280
HTML-CALC: <b>a</b> First integer.
@@ -329,7 +284,6 @@ HTML-CALC: <b>b</b> Second integer.
329284
HTML-CALC: </div>
330285
HTML-CALC: <h3>Returns</h3>
331286
HTML-CALC: <p> double The result of a / b.</p>
332-
HTML-CALC: <p></p>
333287
HTML-CALC: <h3>Throws</h3>
334288
HTML-CALC: <div>
335289
HTML-CALC: <b>std::invalid_argument</b> if b is zero.
@@ -344,12 +298,6 @@ HTML-CALC: <div>
344298
HTML-CALC: <div>
345299
HTML-CALC: <p> Performs the mod operation on integers.</p>
346300
HTML-CALC: </div>
347-
HTML-CALC: <div>
348-
HTML-CALC: <p></p>
349-
HTML-CALC: </div>
350-
HTML-CALC: <div>
351-
HTML-CALC: <p></p>
352-
HTML-CALC: </div>
353301
HTML-CALC: <h3>Parameters</h3>
354302
HTML-CALC: <div>
355303
HTML-CALC: <b>a</b> First integer.
@@ -431,9 +379,6 @@ HTML-RECTANGLE: <div>
431379
HTML-RECTANGLE: <p> Rectangle class derived from Shape.</p>
432380
HTML-RECTANGLE: </div>
433381
HTML-RECTANGLE: <div>
434-
HTML-RECTANGLE: <p></p>
435-
HTML-RECTANGLE: </div>
436-
HTML-RECTANGLE: <div>
437382
HTML-RECTANGLE: <p> Represents a rectangle with a given width and height.</p>
438383
HTML-RECTANGLE: </div>
439384
HTML-RECTANGLE: </div>
@@ -449,12 +394,6 @@ HTML-RECTANGLE: <div>
449394
HTML-RECTANGLE: <div>
450395
HTML-RECTANGLE: <p> Constructs a new Rectangle object.</p>
451396
HTML-RECTANGLE: </div>
452-
HTML-RECTANGLE: <div>
453-
HTML-RECTANGLE: <p></p>
454-
HTML-RECTANGLE: </div>
455-
HTML-RECTANGLE: <div>
456-
HTML-RECTANGLE: <p></p>
457-
HTML-RECTANGLE: </div>
458397
HTML-RECTANGLE: <h3>Parameters</h3>
459398
HTML-RECTANGLE: <div>
460399
HTML-RECTANGLE: <b>width</b> Width of the rectangle.
@@ -472,12 +411,6 @@ HTML-RECTANGLE: <div>
472411
HTML-RECTANGLE: <div>
473412
HTML-RECTANGLE: <p> Calculates the area of the rectangle.</p>
474413
HTML-RECTANGLE: </div>
475-
HTML-RECTANGLE: <div>
476-
HTML-RECTANGLE: <p></p>
477-
HTML-RECTANGLE: </div>
478-
HTML-RECTANGLE: <div>
479-
HTML-RECTANGLE: <p></p>
480-
HTML-RECTANGLE: </div>
481414
HTML-RECTANGLE: <h3>Returns</h3>
482415
HTML-RECTANGLE: <p> double The area of the rectangle.</p>
483416
HTML-RECTANGLE: </div>
@@ -490,12 +423,6 @@ HTML-RECTANGLE: <div>
490423
HTML-RECTANGLE: <div>
491424
HTML-RECTANGLE: <p> Calculates the perimeter of the rectangle.</p>
492425
HTML-RECTANGLE: </div>
493-
HTML-RECTANGLE: <div>
494-
HTML-RECTANGLE: <p></p>
495-
HTML-RECTANGLE: </div>
496-
HTML-RECTANGLE: <div>
497-
HTML-RECTANGLE: <p></p>
498-
HTML-RECTANGLE: </div>
499426
HTML-RECTANGLE: <h3>Returns</h3>
500427
HTML-RECTANGLE: <p> double The perimeter of the rectangle.</p>
501428
HTML-RECTANGLE: </div>
@@ -570,9 +497,6 @@ HTML-CIRCLE: <div>
570497
HTML-CIRCLE: <p> Circle class derived from Shape.</p>
571498
HTML-CIRCLE: </div>
572499
HTML-CIRCLE: <div>
573-
HTML-CIRCLE: <p></p>
574-
HTML-CIRCLE: </div>
575-
HTML-CIRCLE: <div>
576500
HTML-CIRCLE: <p> Represents a circle with a given radius.</p>
577501
HTML-CIRCLE: </div>
578502
HTML-CIRCLE: </div>
@@ -588,12 +512,6 @@ HTML-CIRCLE: <div>
588512
HTML-CIRCLE: <div>
589513
HTML-CIRCLE: <p> Constructs a new Circle object.</p>
590514
HTML-CIRCLE: </div>
591-
HTML-CIRCLE: <div>
592-
HTML-CIRCLE: <p></p>
593-
HTML-CIRCLE: </div>
594-
HTML-CIRCLE: <div>
595-
HTML-CIRCLE: <p></p>
596-
HTML-CIRCLE: </div>
597515
HTML-CIRCLE: <h3>Parameters</h3>
598516
HTML-CIRCLE: <div>
599517
HTML-CIRCLE: <b>radius</b> Radius of the circle.
@@ -608,12 +526,6 @@ HTML-CIRCLE: <div>
608526
HTML-CIRCLE: <div>
609527
HTML-CIRCLE: <p> Calculates the area of the circle.</p>
610528
HTML-CIRCLE: </div>
611-
HTML-CIRCLE: <div>
612-
HTML-CIRCLE: <p></p>
613-
HTML-CIRCLE: </div>
614-
HTML-CIRCLE: <div>
615-
HTML-CIRCLE: <p></p>
616-
HTML-CIRCLE: </div>
617529
HTML-CIRCLE: <h3>Returns</h3>
618530
HTML-CIRCLE: <p> double The area of the circle.</p>
619531
HTML-CIRCLE: </div>
@@ -626,15 +538,6 @@ HTML-CIRCLE: <div>
626538
HTML-CIRCLE: <div>
627539
HTML-CIRCLE: <p> Calculates the perimeter of the circle.</p>
628540
HTML-CIRCLE: </div>
629-
HTML-CIRCLE: <div>
630-
HTML-CIRCLE: <p></p>
631-
HTML-CIRCLE: </div>
632-
HTML-CIRCLE: <div>
633-
HTML-CIRCLE: <p></p>
634-
HTML-CIRCLE: </div>
635-
HTML-CIRCLE: <div>
636-
HTML-CIRCLE: <p></p>
637-
HTML-CIRCLE: </div>
638541
HTML-CIRCLE: <h3>Returns</h3>
639542
HTML-CIRCLE: <p> double The perimeter of the circle.</p>
640543
HTML-CIRCLE: <h3>Code</h3>

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

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,6 @@ struct MyClass {
4747
// CHECK-NEXT: },
4848
// CHECK-NEXT: {
4949
// CHECK-NEXT: "TextComment": " It has some nice methods and fields."
50-
// CHECK-NEXT: },
51-
// CHECK-NEXT: {
52-
// CHECK-NEXT: "TextComment": ""
5350
// CHECK-NEXT: }
5451
// CHECK: "DocumentationFileName": "_ZTV7MyClass",
5552
// CHECK: "Enums": [

0 commit comments

Comments
 (0)