Skip to content

Commit 8059482

Browse files
evelez7evelez7
authored
[clang-doc] add param comments to comment template (#150571)
Serializes parameter comments for all descriptions. We do not support Doxygen's parameter checking, which warns if a documented parameter is not actually present.
1 parent 773e158 commit 8059482

File tree

3 files changed

+100
-2
lines changed

3 files changed

+100
-2
lines changed

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -147,8 +147,10 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
147147
Child.insert({"ParamName", I.ParamName});
148148
Child.insert({"Direction", I.Direction});
149149
Child.insert({"Explicit", I.Explicit});
150-
Child.insert({"Children", ChildArr});
151-
Obj.insert({commentKindToString(I.Kind), ChildVal});
150+
auto TextCommentsArray = extractTextComments(CARef.front().getAsObject());
151+
Child.insert({"Children", TextCommentsArray});
152+
if (I.Kind == CommentKind::CK_ParamCommandComment)
153+
insertComment(Description, ChildVal, "ParamComments");
152154
return Obj;
153155
}
154156

‎clang-tools-extra/clang-doc/assets/comment-template.mustache

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,14 @@
2424
{{>Comments}}
2525
{{/Children}}
2626
{{/ParagraphComment}}
27+
{{#HasParamComments}}
28+
<h3>Parameters</h3>
29+
{{#ParamComments}}
30+
<div>
31+
<b>{{ParamName}}</b> {{#Explicit}}{{Direction}}{{/Explicit}} {{#Children}}{{>Comments}}{{/Children}}
32+
</div>
33+
{{/ParamComments}}
34+
{{/HasParamComments}}
2735
{{#BlockCommandComment}}
2836
<div class="block-command-comment__command">
2937
<div class="block-command-command">

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,23 @@ HTML-CALC: </div>
260260
HTML-CALC: <div>
261261
HTML-CALC: <p></p>
262262
HTML-CALC: </div>
263+
HTML-CALC: <h3>Parameters</h3>
264+
HTML-CALC: <div>
265+
HTML-CALC: <b>a</b> <div>
266+
HTML-CALC: <p> First integer.</p>
267+
HTML-CALC: </div>
268+
HTML-CALC: <div>
269+
HTML-CALC: <p></p>
270+
HTML-CALC: </div>
271+
HTML-CALC: </div>
272+
HTML-CALC: <div>
273+
HTML-CALC: <b>b</b> <div>
274+
HTML-CALC: <p> Second integer.</p>
275+
HTML-CALC: </div>
276+
HTML-CALC: <div>
277+
HTML-CALC: <p></p>
278+
HTML-CALC: </div>
279+
HTML-CALC: </div>
263280
HTML-CALC: </div>
264281
HTML-CALC: </div>
265282
HTML-CALC: </div>
@@ -300,6 +317,23 @@ HTML-CALC: </div>
300317
HTML-CALC: <div>
301318
HTML-CALC: <p></p>
302319
HTML-CALC: </div>
320+
HTML-CALC: <h3>Parameters</h3>
321+
HTML-CALC: <div>
322+
HTML-CALC: <b>a</b> <div>
323+
HTML-CALC: <p> First integer.</p>
324+
HTML-CALC: </div>
325+
HTML-CALC: <div>
326+
HTML-CALC: <p></p>
327+
HTML-CALC: </div>
328+
HTML-CALC: </div>
329+
HTML-CALC: <div>
330+
HTML-CALC: <b>b</b> <div>
331+
HTML-CALC: <p> Second integer.</p>
332+
HTML-CALC: </div>
333+
HTML-CALC: <div>
334+
HTML-CALC: <p></p>
335+
HTML-CALC: </div>
336+
HTML-CALC: </div>
303337
HTML-CALC: </div>
304338
HTML-CALC: </div>
305339
HTML-CALC: </div>
@@ -320,6 +354,23 @@ HTML-CALC: </div>
320354
HTML-CALC: <div>
321355
HTML-CALC: <p></p>
322356
HTML-CALC: </div>
357+
HTML-CALC: <h3>Parameters</h3>
358+
HTML-CALC: <div>
359+
HTML-CALC: <b>a</b> <div>
360+
HTML-CALC: <p> First integer.</p>
361+
HTML-CALC: </div>
362+
HTML-CALC: <div>
363+
HTML-CALC: <p></p>
364+
HTML-CALC: </div>
365+
HTML-CALC: </div>
366+
HTML-CALC: <div>
367+
HTML-CALC: <b>b</b> <div>
368+
HTML-CALC: <p> Second integer.</p>
369+
HTML-CALC: </div>
370+
HTML-CALC: <div>
371+
HTML-CALC: <p></p>
372+
HTML-CALC: </div>
373+
HTML-CALC: </div>
323374
HTML-CALC: </div>
324375
HTML-CALC: </div>
325376
HTML-CALC: </div>
@@ -340,6 +391,23 @@ HTML-CALC: </div>
340391
HTML-CALC: <div>
341392
HTML-CALC: <p></p>
342393
HTML-CALC: </div>
394+
HTML-CALC: <h3>Parameters</h3>
395+
HTML-CALC: <div>
396+
HTML-CALC: <b>a</b> <div>
397+
HTML-CALC: <p> First integer.</p>
398+
HTML-CALC: </div>
399+
HTML-CALC: <div>
400+
HTML-CALC: <p></p>
401+
HTML-CALC: </div>
402+
HTML-CALC: </div>
403+
HTML-CALC: <div>
404+
HTML-CALC: <b>b</b> <div>
405+
HTML-CALC: <p> Second integer.</p>
406+
HTML-CALC: </div>
407+
HTML-CALC: <div>
408+
HTML-CALC: <p></p>
409+
HTML-CALC: </div>
410+
HTML-CALC: </div>
343411
HTML-CALC: </div>
344412
HTML-CALC: </div>
345413
HTML-CALC: </div>
@@ -439,6 +507,20 @@ HTML-RECTANGLE: </div>
439507
HTML-RECTANGLE: <div>
440508
HTML-RECTANGLE: <p></p>
441509
HTML-RECTANGLE: </div>
510+
HTML-RECTANGLE: <h3>Parameters</h3>
511+
HTML-RECTANGLE: <div>
512+
HTML-RECTANGLE: <b>width</b> <div>
513+
HTML-RECTANGLE: <p> Width of the rectangle.</p>
514+
HTML-RECTANGLE: </div>
515+
HTML-RECTANGLE: <div>
516+
HTML-RECTANGLE: <p></p>
517+
HTML-RECTANGLE: </div>
518+
HTML-RECTANGLE: </div>
519+
HTML-RECTANGLE: <div>
520+
HTML-RECTANGLE: <b>height</b> <div>
521+
HTML-RECTANGLE: <p> Height of the rectangle.</p>
522+
HTML-RECTANGLE: </div>
523+
HTML-RECTANGLE: </div>
442524
HTML-RECTANGLE: </div>
443525
HTML-RECTANGLE: </div>
444526
HTML-RECTANGLE: </div>
@@ -578,6 +660,12 @@ HTML-CIRCLE: </div>
578660
HTML-CIRCLE: <div>
579661
HTML-CIRCLE: <p></p>
580662
HTML-CIRCLE: </div>
663+
HTML-CIRCLE: <h3>Parameters</h3>
664+
HTML-CIRCLE: <div>
665+
HTML-CIRCLE: <b>radius</b> <div>
666+
HTML-CIRCLE: <p> Radius of the circle.</p>
667+
HTML-CIRCLE: </div>
668+
HTML-CIRCLE: </div>
581669
HTML-CIRCLE: </div>
582670
HTML-CIRCLE: </div>
583671
HTML-CIRCLE: </div>

0 commit comments

Comments
 (0)