1//===--- Comment.h - Comment AST nodes --------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file defines comment AST nodes.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_CLANG_AST_COMMENT_H
14#define LLVM_CLANG_AST_COMMENT_H
15
16#include "clang/AST/CommentCommandTraits.h"
17#include "clang/AST/DeclObjC.h"
18#include "clang/AST/Type.h"
19#include "clang/Basic/SourceLocation.h"
20#include "llvm/ADT/ArrayRef.h"
21#include "llvm/ADT/StringRef.h"
22#include "llvm/Support/Compiler.h"
23
24namespace clang {
25class Decl;
26class ParmVarDecl;
27class TemplateParameterList;
28
29namespace comments {
30class FullComment;
31enum class InlineCommandRenderKind;
32enum class ParamCommandPassDirection;
33
34/// Describes the syntax that was used in a documentation command.
35///
36/// Exact values of this enumeration are important because they used to select
37/// parts of diagnostic messages. Audit diagnostics before changing or adding
38/// a new value.
39enum CommandMarkerKind {
40 /// Command started with a backslash character:
41 /// \code
42 /// \foo
43 /// \endcode
44 CMK_Backslash = 0,
45
46 /// Command started with an 'at' character:
47 /// \code
48 /// @foo
49 /// \endcode
50 CMK_At = 1
51};
52
53enum class CommentKind {
54 None = 0,
55#define COMMENT(CLASS, PARENT) CLASS,
56#define COMMENT_RANGE(BASE, FIRST, LAST) \
57 First##BASE##Constant = FIRST, Last##BASE##Constant = LAST,
58#define LAST_COMMENT_RANGE(BASE, FIRST, LAST) \
59 First##BASE##Constant = FIRST, Last##BASE##Constant = LAST
60#define ABSTRACT_COMMENT(COMMENT)
61#include "clang/AST/CommentNodes.inc"
62};
63
64/// Any part of the comment.
65/// Abstract class.
66class Comment {
67protected:
68 /// Preferred location to show caret.
69 SourceLocation Loc;
70
71 /// Source range of this AST node.
72 SourceRange Range;
73
74 class CommentBitfields {
75 friend class Comment;
76
77 /// Type of this AST node.
78 LLVM_PREFERRED_TYPE(CommentKind)
79 unsigned Kind : 8;
80 };
81 enum { NumCommentBits = 8 };
82
83 class InlineContentCommentBitfields {
84 friend class InlineContentComment;
85
86 LLVM_PREFERRED_TYPE(CommentBitfields)
87 unsigned : NumCommentBits;
88
89 /// True if there is a newline after this inline content node.
90 /// (There is no separate AST node for a newline.)
91 LLVM_PREFERRED_TYPE(bool)
92 unsigned HasTrailingNewline : 1;
93 };
94 enum { NumInlineContentCommentBits = NumCommentBits + 1 };
95
96 class TextCommentBitfields {
97 friend class TextComment;
98
99 LLVM_PREFERRED_TYPE(InlineContentCommentBitfields)
100 unsigned : NumInlineContentCommentBits;
101
102 /// True if \c IsWhitespace field contains a valid value.
103 LLVM_PREFERRED_TYPE(bool)
104 mutable unsigned IsWhitespaceValid : 1;
105
106 /// True if this comment AST node contains only whitespace.
107 LLVM_PREFERRED_TYPE(bool)
108 mutable unsigned IsWhitespace : 1;
109 };
110 enum { NumTextCommentBits = NumInlineContentCommentBits + 2 };
111
112 class InlineCommandCommentBitfields {
113 friend class InlineCommandComment;
114
115 LLVM_PREFERRED_TYPE(InlineContentCommentBitfields)
116 unsigned : NumInlineContentCommentBits;
117
118 LLVM_PREFERRED_TYPE(InlineCommandRenderKind)
119 unsigned RenderKind : 3;
120
121 LLVM_PREFERRED_TYPE(CommandTraits::KnownCommandIDs)
122 unsigned CommandID : CommandInfo::NumCommandIDBits;
123
124 /// Describes the syntax that was used in a documentation command.
125 /// Contains values from CommandMarkerKind enum.
126 LLVM_PREFERRED_TYPE(CommandMarkerKind)
127 unsigned CommandMarker : 1;
128 };
129 enum { NumInlineCommandCommentBits = NumInlineContentCommentBits + 3 +
130 CommandInfo::NumCommandIDBits };
131
132 class HTMLTagCommentBitfields {
133 friend class HTMLTagComment;
134
135 LLVM_PREFERRED_TYPE(InlineContentCommentBitfields)
136 unsigned : NumInlineContentCommentBits;
137
138 /// True if we found that this tag is malformed in some way.
139 LLVM_PREFERRED_TYPE(bool)
140 unsigned IsMalformed : 1;
141 };
142 enum { NumHTMLTagCommentBits = NumInlineContentCommentBits + 1 };
143
144 class HTMLStartTagCommentBitfields {
145 friend class HTMLStartTagComment;
146
147 LLVM_PREFERRED_TYPE(HTMLTagCommentBitfields)
148 unsigned : NumHTMLTagCommentBits;
149
150 /// True if this tag is self-closing (e. g., <br />). This is based on tag
151 /// spelling in comment (plain <br> would not set this flag).
152 LLVM_PREFERRED_TYPE(bool)
153 unsigned IsSelfClosing : 1;
154 };
155 enum { NumHTMLStartTagCommentBits = NumHTMLTagCommentBits + 1 };
156
157 class ParagraphCommentBitfields {
158 friend class ParagraphComment;
159
160 LLVM_PREFERRED_TYPE(CommentBitfields)
161 unsigned : NumCommentBits;
162
163 /// True if \c IsWhitespace field contains a valid value.
164 LLVM_PREFERRED_TYPE(bool)
165 mutable unsigned IsWhitespaceValid : 1;
166
167 /// True if this comment AST node contains only whitespace.
168 LLVM_PREFERRED_TYPE(bool)
169 mutable unsigned IsWhitespace : 1;
170 };
171 enum { NumParagraphCommentBits = NumCommentBits + 2 };
172
173 class BlockCommandCommentBitfields {
174 friend class BlockCommandComment;
175
176 LLVM_PREFERRED_TYPE(CommentBitfields)
177 unsigned : NumCommentBits;
178
179 LLVM_PREFERRED_TYPE(CommandTraits::KnownCommandIDs)
180 unsigned CommandID : CommandInfo::NumCommandIDBits;
181
182 /// Describes the syntax that was used in a documentation command.
183 /// Contains values from CommandMarkerKind enum.
184 LLVM_PREFERRED_TYPE(CommandMarkerKind)
185 unsigned CommandMarker : 1;
186 };
187 enum { NumBlockCommandCommentBits = NumCommentBits +
188 CommandInfo::NumCommandIDBits + 1 };
189
190 class ParamCommandCommentBitfields {
191 friend class ParamCommandComment;
192
193 LLVM_PREFERRED_TYPE(BlockCommandCommentBitfields)
194 unsigned : NumBlockCommandCommentBits;
195
196 /// Parameter passing direction.
197 LLVM_PREFERRED_TYPE(ParamCommandPassDirection)
198 unsigned Direction : 2;
199
200 /// True if direction was specified explicitly in the comment.
201 LLVM_PREFERRED_TYPE(bool)
202 unsigned IsDirectionExplicit : 1;
203 };
204 enum { NumParamCommandCommentBits = NumBlockCommandCommentBits + 3 };
205
206 union {
207 CommentBitfields CommentBits;
208 InlineContentCommentBitfields InlineContentCommentBits;
209 TextCommentBitfields TextCommentBits;
210 InlineCommandCommentBitfields InlineCommandCommentBits;
211 HTMLTagCommentBitfields HTMLTagCommentBits;
212 HTMLStartTagCommentBitfields HTMLStartTagCommentBits;
213 ParagraphCommentBitfields ParagraphCommentBits;
214 BlockCommandCommentBitfields BlockCommandCommentBits;
215 ParamCommandCommentBitfields ParamCommandCommentBits;
216 };
217
218 void setSourceRange(SourceRange SR) {
219 Range = SR;
220 }
221
222 void setLocation(SourceLocation L) {
223 Loc = L;
224 }
225
226public:
227 struct Argument {
228 SourceRange Range;
229 StringRef Text;
230 };
231
232 Comment(CommentKind K,
233 SourceLocation LocBegin,
234 SourceLocation LocEnd) :
235 Loc(LocBegin), Range(SourceRange(LocBegin, LocEnd)) {
236 CommentBits.Kind = llvm::to_underlying(E: K);
237 }
238
239 CommentKind getCommentKind() const {
240 return static_cast<CommentKind>(CommentBits.Kind);
241 }
242
243 const char *getCommentKindName() const;
244
245 void dump() const;
246 void dumpColor() const;
247 void dump(raw_ostream &OS, const ASTContext &Context) const;
248
249 SourceRange getSourceRange() const LLVM_READONLY { return Range; }
250
251 SourceLocation getBeginLoc() const LLVM_READONLY { return Range.getBegin(); }
252
253 SourceLocation getEndLoc() const LLVM_READONLY { return Range.getEnd(); }
254
255 SourceLocation getLocation() const LLVM_READONLY { return Loc; }
256
257 typedef Comment * const *child_iterator;
258
259 child_iterator child_begin() const;
260 child_iterator child_end() const;
261
262 // TODO: const child iterator
263
264 unsigned child_count() const {
265 return child_end() - child_begin();
266 }
267};
268
269/// Inline content (contained within a block).
270/// Abstract class.
271class InlineContentComment : public Comment {
272protected:
273 InlineContentComment(CommentKind K,
274 SourceLocation LocBegin,
275 SourceLocation LocEnd) :
276 Comment(K, LocBegin, LocEnd) {
277 InlineContentCommentBits.HasTrailingNewline = 0;
278 }
279
280public:
281 static bool classof(const Comment *C) {
282 return C->getCommentKind() >=
283 CommentKind::FirstInlineContentCommentConstant &&
284 C->getCommentKind() <= CommentKind::LastInlineContentCommentConstant;
285 }
286
287 void addTrailingNewline() {
288 InlineContentCommentBits.HasTrailingNewline = 1;
289 }
290
291 bool hasTrailingNewline() const {
292 return InlineContentCommentBits.HasTrailingNewline;
293 }
294};
295
296/// Plain text.
297class TextComment : public InlineContentComment {
298 StringRef Text;
299
300public:
301 TextComment(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text)
302 : InlineContentComment(CommentKind::TextComment, LocBegin, LocEnd),
303 Text(Text) {
304 TextCommentBits.IsWhitespaceValid = false;
305 }
306
307 static bool classof(const Comment *C) {
308 return C->getCommentKind() == CommentKind::TextComment;
309 }
310
311 child_iterator child_begin() const { return nullptr; }
312
313 child_iterator child_end() const { return nullptr; }
314
315 StringRef getText() const LLVM_READONLY { return Text; }
316
317 bool isWhitespace() const {
318 if (TextCommentBits.IsWhitespaceValid)
319 return TextCommentBits.IsWhitespace;
320
321 TextCommentBits.IsWhitespace = isWhitespaceNoCache();
322 TextCommentBits.IsWhitespaceValid = true;
323 return TextCommentBits.IsWhitespace;
324 }
325
326private:
327 bool isWhitespaceNoCache() const;
328};
329
330/// The most appropriate rendering mode for this command, chosen on command
331/// semantics in Doxygen.
332enum class InlineCommandRenderKind {
333 Normal,
334 Bold,
335 Monospaced,
336 Emphasized,
337 Anchor
338};
339
340/// A command with word-like arguments that is considered inline content.
341class InlineCommandComment : public InlineContentComment {
342protected:
343 /// Command arguments.
344 ArrayRef<Argument> Args;
345
346public:
347 InlineCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
348 unsigned CommandID, InlineCommandRenderKind RK,
349 CommandMarkerKind CommandMarker, ArrayRef<Argument> Args)
350 : InlineContentComment(CommentKind::InlineCommandComment, LocBegin,
351 LocEnd),
352 Args(Args) {
353 InlineCommandCommentBits.RenderKind = llvm::to_underlying(E: RK);
354 InlineCommandCommentBits.CommandID = CommandID;
355 InlineCommandCommentBits.CommandMarker = llvm::to_underlying(E: CommandMarker);
356 }
357
358 static bool classof(const Comment *C) {
359 return C->getCommentKind() == CommentKind::InlineCommandComment;
360 }
361
362 child_iterator child_begin() const { return nullptr; }
363
364 child_iterator child_end() const { return nullptr; }
365
366 unsigned getCommandID() const {
367 return InlineCommandCommentBits.CommandID;
368 }
369
370 StringRef getCommandName(const CommandTraits &Traits) const {
371 return Traits.getCommandInfo(CommandID: getCommandID())->Name;
372 }
373
374 SourceRange getCommandNameRange() const {
375 return SourceRange(getBeginLoc().getLocWithOffset(Offset: -1), getEndLoc());
376 }
377
378 InlineCommandRenderKind getRenderKind() const {
379 return static_cast<InlineCommandRenderKind>(
380 InlineCommandCommentBits.RenderKind);
381 }
382
383 unsigned getNumArgs() const {
384 return Args.size();
385 }
386
387 StringRef getArgText(unsigned Idx) const {
388 return Args[Idx].Text;
389 }
390
391 SourceRange getArgRange(unsigned Idx) const {
392 return Args[Idx].Range;
393 }
394
395 CommandMarkerKind getCommandMarker() const {
396 return static_cast<CommandMarkerKind>(
397 InlineCommandCommentBits.CommandMarker);
398 }
399};
400
401/// Abstract class for opening and closing HTML tags. HTML tags are always
402/// treated as inline content (regardless HTML semantics).
403class HTMLTagComment : public InlineContentComment {
404protected:
405 StringRef TagName;
406 SourceRange TagNameRange;
407
408 HTMLTagComment(CommentKind K,
409 SourceLocation LocBegin,
410 SourceLocation LocEnd,
411 StringRef TagName,
412 SourceLocation TagNameBegin,
413 SourceLocation TagNameEnd) :
414 InlineContentComment(K, LocBegin, LocEnd),
415 TagName(TagName),
416 TagNameRange(TagNameBegin, TagNameEnd) {
417 setLocation(TagNameBegin);
418 HTMLTagCommentBits.IsMalformed = 0;
419 }
420
421public:
422 static bool classof(const Comment *C) {
423 return C->getCommentKind() >= CommentKind::FirstHTMLTagCommentConstant &&
424 C->getCommentKind() <= CommentKind::LastHTMLTagCommentConstant;
425 }
426
427 StringRef getTagName() const LLVM_READONLY { return TagName; }
428
429 SourceRange getTagNameSourceRange() const LLVM_READONLY {
430 SourceLocation L = getLocation();
431 return SourceRange(L.getLocWithOffset(Offset: 1),
432 L.getLocWithOffset(Offset: 1 + TagName.size()));
433 }
434
435 bool isMalformed() const {
436 return HTMLTagCommentBits.IsMalformed;
437 }
438
439 void setIsMalformed() {
440 HTMLTagCommentBits.IsMalformed = 1;
441 }
442};
443
444/// An opening HTML tag with attributes.
445class HTMLStartTagComment : public HTMLTagComment {
446public:
447 class Attribute {
448 public:
449 SourceLocation NameLocBegin;
450 StringRef Name;
451
452 SourceLocation EqualsLoc;
453
454 SourceRange ValueRange;
455 StringRef Value;
456
457 Attribute() { }
458
459 Attribute(SourceLocation NameLocBegin, StringRef Name)
460 : NameLocBegin(NameLocBegin), Name(Name), EqualsLoc(SourceLocation()) {}
461
462 Attribute(SourceLocation NameLocBegin, StringRef Name,
463 SourceLocation EqualsLoc, SourceRange ValueRange, StringRef Value)
464 : NameLocBegin(NameLocBegin), Name(Name), EqualsLoc(EqualsLoc),
465 ValueRange(ValueRange), Value(Value) {}
466
467 SourceLocation getNameLocEnd() const {
468 return NameLocBegin.getLocWithOffset(Offset: Name.size());
469 }
470
471 SourceRange getNameRange() const {
472 return SourceRange(NameLocBegin, getNameLocEnd());
473 }
474 };
475
476private:
477 ArrayRef<Attribute> Attributes;
478
479public:
480 HTMLStartTagComment(SourceLocation LocBegin, StringRef TagName)
481 : HTMLTagComment(CommentKind::HTMLStartTagComment, LocBegin,
482 LocBegin.getLocWithOffset(Offset: 1 + TagName.size()), TagName,
483 LocBegin.getLocWithOffset(Offset: 1),
484 LocBegin.getLocWithOffset(Offset: 1 + TagName.size())) {
485 HTMLStartTagCommentBits.IsSelfClosing = false;
486 }
487
488 static bool classof(const Comment *C) {
489 return C->getCommentKind() == CommentKind::HTMLStartTagComment;
490 }
491
492 child_iterator child_begin() const { return nullptr; }
493
494 child_iterator child_end() const { return nullptr; }
495
496 unsigned getNumAttrs() const {
497 return Attributes.size();
498 }
499
500 const Attribute &getAttr(unsigned Idx) const {
501 return Attributes[Idx];
502 }
503
504 void setAttrs(ArrayRef<Attribute> Attrs) {
505 Attributes = Attrs;
506 if (!Attrs.empty()) {
507 const Attribute &Attr = Attrs.back();
508 SourceLocation L = Attr.ValueRange.getEnd();
509 if (L.isValid())
510 Range.setEnd(L);
511 else {
512 Range.setEnd(Attr.getNameLocEnd());
513 }
514 }
515 }
516
517 void setGreaterLoc(SourceLocation GreaterLoc) {
518 Range.setEnd(GreaterLoc);
519 }
520
521 bool isSelfClosing() const {
522 return HTMLStartTagCommentBits.IsSelfClosing;
523 }
524
525 void setSelfClosing() {
526 HTMLStartTagCommentBits.IsSelfClosing = true;
527 }
528};
529
530/// A closing HTML tag.
531class HTMLEndTagComment : public HTMLTagComment {
532public:
533 HTMLEndTagComment(SourceLocation LocBegin, SourceLocation LocEnd,
534 StringRef TagName)
535 : HTMLTagComment(CommentKind::HTMLEndTagComment, LocBegin, LocEnd,
536 TagName, LocBegin.getLocWithOffset(Offset: 2),
537 LocBegin.getLocWithOffset(Offset: 2 + TagName.size())) {}
538
539 static bool classof(const Comment *C) {
540 return C->getCommentKind() == CommentKind::HTMLEndTagComment;
541 }
542
543 child_iterator child_begin() const { return nullptr; }
544
545 child_iterator child_end() const { return nullptr; }
546};
547
548/// Block content (contains inline content).
549/// Abstract class.
550class BlockContentComment : public Comment {
551protected:
552 BlockContentComment(CommentKind K,
553 SourceLocation LocBegin,
554 SourceLocation LocEnd) :
555 Comment(K, LocBegin, LocEnd)
556 { }
557
558public:
559 static bool classof(const Comment *C) {
560 return C->getCommentKind() >=
561 CommentKind::FirstBlockContentCommentConstant &&
562 C->getCommentKind() <= CommentKind::LastBlockContentCommentConstant;
563 }
564};
565
566/// A single paragraph that contains inline content.
567class ParagraphComment : public BlockContentComment {
568 ArrayRef<InlineContentComment *> Content;
569
570public:
571 ParagraphComment(ArrayRef<InlineContentComment *> Content)
572 : BlockContentComment(CommentKind::ParagraphComment, SourceLocation(),
573 SourceLocation()),
574 Content(Content) {
575 if (Content.empty()) {
576 ParagraphCommentBits.IsWhitespace = true;
577 ParagraphCommentBits.IsWhitespaceValid = true;
578 return;
579 }
580
581 ParagraphCommentBits.IsWhitespaceValid = false;
582
583 setSourceRange(SourceRange(Content.front()->getBeginLoc(),
584 Content.back()->getEndLoc()));
585 setLocation(Content.front()->getBeginLoc());
586 }
587
588 static bool classof(const Comment *C) {
589 return C->getCommentKind() == CommentKind::ParagraphComment;
590 }
591
592 child_iterator child_begin() const {
593 return reinterpret_cast<child_iterator>(Content.begin());
594 }
595
596 child_iterator child_end() const {
597 return reinterpret_cast<child_iterator>(Content.end());
598 }
599
600 bool isWhitespace() const {
601 if (ParagraphCommentBits.IsWhitespaceValid)
602 return ParagraphCommentBits.IsWhitespace;
603
604 ParagraphCommentBits.IsWhitespace = isWhitespaceNoCache();
605 ParagraphCommentBits.IsWhitespaceValid = true;
606 return ParagraphCommentBits.IsWhitespace;
607 }
608
609private:
610 bool isWhitespaceNoCache() const;
611};
612
613/// A command that has zero or more word-like arguments (number of word-like
614/// arguments depends on command name) and a paragraph as an argument
615/// (e. g., \\brief).
616class BlockCommandComment : public BlockContentComment {
617protected:
618 /// Word-like arguments.
619 ArrayRef<Argument> Args;
620
621 /// Paragraph argument.
622 ParagraphComment *Paragraph;
623
624 BlockCommandComment(CommentKind K,
625 SourceLocation LocBegin,
626 SourceLocation LocEnd,
627 unsigned CommandID,
628 CommandMarkerKind CommandMarker) :
629 BlockContentComment(K, LocBegin, LocEnd),
630 Paragraph(nullptr) {
631 setLocation(getCommandNameBeginLoc());
632 BlockCommandCommentBits.CommandID = CommandID;
633 BlockCommandCommentBits.CommandMarker = CommandMarker;
634 }
635
636public:
637 BlockCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
638 unsigned CommandID, CommandMarkerKind CommandMarker)
639 : BlockContentComment(CommentKind::BlockCommandComment, LocBegin, LocEnd),
640 Paragraph(nullptr) {
641 setLocation(getCommandNameBeginLoc());
642 BlockCommandCommentBits.CommandID = CommandID;
643 BlockCommandCommentBits.CommandMarker = CommandMarker;
644 }
645
646 static bool classof(const Comment *C) {
647 return C->getCommentKind() >=
648 CommentKind::FirstBlockCommandCommentConstant &&
649 C->getCommentKind() <= CommentKind::LastBlockCommandCommentConstant;
650 }
651
652 child_iterator child_begin() const {
653 return reinterpret_cast<child_iterator>(&Paragraph);
654 }
655
656 child_iterator child_end() const {
657 return reinterpret_cast<child_iterator>(&Paragraph + 1);
658 }
659
660 unsigned getCommandID() const {
661 return BlockCommandCommentBits.CommandID;
662 }
663
664 StringRef getCommandName(const CommandTraits &Traits) const {
665 return Traits.getCommandInfo(CommandID: getCommandID())->Name;
666 }
667
668 SourceLocation getCommandNameBeginLoc() const {
669 return getBeginLoc().getLocWithOffset(Offset: 1);
670 }
671
672 SourceRange getCommandNameRange(const CommandTraits &Traits) const {
673 StringRef Name = getCommandName(Traits);
674 return SourceRange(getCommandNameBeginLoc(),
675 getBeginLoc().getLocWithOffset(Offset: 1 + Name.size()));
676 }
677
678 unsigned getNumArgs() const {
679 return Args.size();
680 }
681
682 StringRef getArgText(unsigned Idx) const {
683 return Args[Idx].Text;
684 }
685
686 SourceRange getArgRange(unsigned Idx) const {
687 return Args[Idx].Range;
688 }
689
690 void setArgs(ArrayRef<Argument> A) {
691 Args = A;
692 if (Args.size() > 0) {
693 SourceLocation NewLocEnd = Args.back().Range.getEnd();
694 if (NewLocEnd.isValid())
695 setSourceRange(SourceRange(getBeginLoc(), NewLocEnd));
696 }
697 }
698
699 ParagraphComment *getParagraph() const LLVM_READONLY {
700 return Paragraph;
701 }
702
703 bool hasNonWhitespaceParagraph() const {
704 return Paragraph && !Paragraph->isWhitespace();
705 }
706
707 void setParagraph(ParagraphComment *PC) {
708 Paragraph = PC;
709 SourceLocation NewLocEnd = PC->getEndLoc();
710 if (NewLocEnd.isValid())
711 setSourceRange(SourceRange(getBeginLoc(), NewLocEnd));
712 }
713
714 CommandMarkerKind getCommandMarker() const LLVM_READONLY {
715 return static_cast<CommandMarkerKind>(
716 BlockCommandCommentBits.CommandMarker);
717 }
718};
719
720enum class ParamCommandPassDirection { In, Out, InOut };
721
722/// Doxygen \\param command.
723class ParamCommandComment : public BlockCommandComment {
724private:
725 /// Parameter index in the function declaration.
726 unsigned ParamIndex;
727
728public:
729 enum : unsigned {
730 InvalidParamIndex = ~0U,
731 VarArgParamIndex = ~0U/*InvalidParamIndex*/ - 1U
732 };
733
734 ParamCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
735 unsigned CommandID, CommandMarkerKind CommandMarker)
736 : BlockCommandComment(CommentKind::ParamCommandComment, LocBegin, LocEnd,
737 CommandID, CommandMarker),
738 ParamIndex(InvalidParamIndex) {
739 ParamCommandCommentBits.Direction =
740 llvm::to_underlying(E: ParamCommandPassDirection::In);
741 ParamCommandCommentBits.IsDirectionExplicit = false;
742 }
743
744 static bool classof(const Comment *C) {
745 return C->getCommentKind() == CommentKind::ParamCommandComment;
746 }
747
748 static const char *getDirectionAsString(ParamCommandPassDirection D);
749
750 ParamCommandPassDirection getDirection() const LLVM_READONLY {
751 return static_cast<ParamCommandPassDirection>(
752 ParamCommandCommentBits.Direction);
753 }
754
755 bool isDirectionExplicit() const LLVM_READONLY {
756 return ParamCommandCommentBits.IsDirectionExplicit;
757 }
758
759 void setDirection(ParamCommandPassDirection Direction, bool Explicit) {
760 ParamCommandCommentBits.Direction = llvm::to_underlying(E: Direction);
761 ParamCommandCommentBits.IsDirectionExplicit = Explicit;
762 }
763
764 bool hasParamName() const {
765 return getNumArgs() > 0;
766 }
767
768 StringRef getParamName(const FullComment *FC) const;
769
770 StringRef getParamNameAsWritten() const {
771 return Args[0].Text;
772 }
773
774 SourceRange getParamNameRange() const {
775 return Args[0].Range;
776 }
777
778 bool isParamIndexValid() const LLVM_READONLY {
779 return ParamIndex != InvalidParamIndex;
780 }
781
782 bool isVarArgParam() const LLVM_READONLY {
783 return ParamIndex == VarArgParamIndex;
784 }
785
786 void setIsVarArgParam() {
787 ParamIndex = VarArgParamIndex;
788 assert(isParamIndexValid());
789 }
790
791 unsigned getParamIndex() const LLVM_READONLY {
792 assert(isParamIndexValid());
793 assert(!isVarArgParam());
794 return ParamIndex;
795 }
796
797 void setParamIndex(unsigned Index) {
798 ParamIndex = Index;
799 assert(isParamIndexValid());
800 assert(!isVarArgParam());
801 }
802};
803
804/// Doxygen \\tparam command, describes a template parameter.
805class TParamCommandComment : public BlockCommandComment {
806private:
807 /// If this template parameter name was resolved (found in template parameter
808 /// list), then this stores a list of position indexes in all template
809 /// parameter lists.
810 ///
811 /// For example:
812 /// \verbatim
813 /// template<typename C, template<typename T> class TT>
814 /// void test(TT<int> aaa);
815 /// \endverbatim
816 /// For C: Position = { 0 }
817 /// For TT: Position = { 1 }
818 /// For T: Position = { 1, 0 }
819 ArrayRef<unsigned> Position;
820
821public:
822 TParamCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
823 unsigned CommandID, CommandMarkerKind CommandMarker)
824 : BlockCommandComment(CommentKind::TParamCommandComment, LocBegin, LocEnd,
825 CommandID, CommandMarker) {}
826
827 static bool classof(const Comment *C) {
828 return C->getCommentKind() == CommentKind::TParamCommandComment;
829 }
830
831 bool hasParamName() const {
832 return getNumArgs() > 0;
833 }
834
835 StringRef getParamName(const FullComment *FC) const;
836
837 StringRef getParamNameAsWritten() const {
838 return Args[0].Text;
839 }
840
841 SourceRange getParamNameRange() const {
842 return Args[0].Range;
843 }
844
845 bool isPositionValid() const LLVM_READONLY {
846 return !Position.empty();
847 }
848
849 unsigned getDepth() const {
850 assert(isPositionValid());
851 return Position.size();
852 }
853
854 unsigned getIndex(unsigned Depth) const {
855 assert(isPositionValid());
856 return Position[Depth];
857 }
858
859 void setPosition(ArrayRef<unsigned> NewPosition) {
860 Position = NewPosition;
861 assert(isPositionValid());
862 }
863};
864
865/// A line of text contained in a verbatim block.
866class VerbatimBlockLineComment : public Comment {
867 StringRef Text;
868
869public:
870 VerbatimBlockLineComment(SourceLocation LocBegin, StringRef Text)
871 : Comment(CommentKind::VerbatimBlockLineComment, LocBegin,
872 LocBegin.getLocWithOffset(Offset: Text.size())),
873 Text(Text) {}
874
875 static bool classof(const Comment *C) {
876 return C->getCommentKind() == CommentKind::VerbatimBlockLineComment;
877 }
878
879 child_iterator child_begin() const { return nullptr; }
880
881 child_iterator child_end() const { return nullptr; }
882
883 StringRef getText() const LLVM_READONLY {
884 return Text;
885 }
886};
887
888/// A verbatim block command (e. g., preformatted code). Verbatim block has an
889/// opening and a closing command and contains multiple lines of text
890/// (VerbatimBlockLineComment nodes).
891class VerbatimBlockComment : public BlockCommandComment {
892protected:
893 StringRef CloseName;
894 SourceLocation CloseNameLocBegin;
895 ArrayRef<VerbatimBlockLineComment *> Lines;
896
897public:
898 VerbatimBlockComment(SourceLocation LocBegin, SourceLocation LocEnd,
899 unsigned CommandID)
900 : BlockCommandComment(CommentKind::VerbatimBlockComment, LocBegin, LocEnd,
901 CommandID,
902 CMK_At) // FIXME: improve source fidelity.
903 {}
904
905 static bool classof(const Comment *C) {
906 return C->getCommentKind() == CommentKind::VerbatimBlockComment;
907 }
908
909 child_iterator child_begin() const {
910 return reinterpret_cast<child_iterator>(Lines.begin());
911 }
912
913 child_iterator child_end() const {
914 return reinterpret_cast<child_iterator>(Lines.end());
915 }
916
917 void setCloseName(StringRef Name, SourceLocation LocBegin) {
918 CloseName = Name;
919 CloseNameLocBegin = LocBegin;
920 }
921
922 void setLines(ArrayRef<VerbatimBlockLineComment *> L) {
923 Lines = L;
924 }
925
926 StringRef getCloseName() const {
927 return CloseName;
928 }
929
930 unsigned getNumLines() const {
931 return Lines.size();
932 }
933
934 StringRef getText(unsigned LineIdx) const {
935 return Lines[LineIdx]->getText();
936 }
937};
938
939/// A verbatim line command. Verbatim line has an opening command, a single
940/// line of text (up to the newline after the opening command) and has no
941/// closing command.
942class VerbatimLineComment : public BlockCommandComment {
943protected:
944 StringRef Text;
945 SourceLocation TextBegin;
946
947public:
948 VerbatimLineComment(SourceLocation LocBegin, SourceLocation LocEnd,
949 unsigned CommandID, SourceLocation TextBegin,
950 StringRef Text)
951 : BlockCommandComment(CommentKind::VerbatimLineComment, LocBegin, LocEnd,
952 CommandID,
953 CMK_At), // FIXME: improve source fidelity.
954 Text(Text), TextBegin(TextBegin) {}
955
956 static bool classof(const Comment *C) {
957 return C->getCommentKind() == CommentKind::VerbatimLineComment;
958 }
959
960 child_iterator child_begin() const { return nullptr; }
961
962 child_iterator child_end() const { return nullptr; }
963
964 StringRef getText() const {
965 return Text;
966 }
967
968 SourceRange getTextRange() const {
969 return SourceRange(TextBegin, getEndLoc());
970 }
971};
972
973/// Information about the declaration, useful to clients of FullComment.
974struct DeclInfo {
975 /// Declaration the comment is actually attached to (in the source).
976 /// Should not be NULL.
977 const Decl *CommentDecl;
978
979 /// CurrentDecl is the declaration with which the FullComment is associated.
980 ///
981 /// It can be different from \c CommentDecl. It happens when we decide
982 /// that the comment originally attached to \c CommentDecl is fine for
983 /// \c CurrentDecl too (for example, for a redeclaration or an overrider of
984 /// \c CommentDecl).
985 ///
986 /// The information in the DeclInfo corresponds to CurrentDecl.
987 const Decl *CurrentDecl;
988
989 /// Parameters that can be referenced by \\param if \c CommentDecl is something
990 /// that we consider a "function".
991 ArrayRef<const ParmVarDecl *> ParamVars;
992
993 /// Function return type if \c CommentDecl is something that we consider
994 /// a "function".
995 QualType ReturnType;
996
997 /// Template parameters that can be referenced by \\tparam if \c CommentDecl is
998 /// a template (\c IsTemplateDecl or \c IsTemplatePartialSpecialization is
999 /// true).
1000 const TemplateParameterList *TemplateParameters;
1001
1002 /// A simplified description of \c CommentDecl kind that should be good enough
1003 /// for documentation rendering purposes.
1004 enum DeclKind {
1005 /// Everything else not explicitly mentioned below.
1006 OtherKind,
1007
1008 /// Something that we consider a "function":
1009 /// \li function,
1010 /// \li function template,
1011 /// \li function template specialization,
1012 /// \li member function,
1013 /// \li member function template,
1014 /// \li member function template specialization,
1015 /// \li ObjC method,
1016 FunctionKind,
1017
1018 /// Something that we consider a "class":
1019 /// \li class/struct,
1020 /// \li class template,
1021 /// \li class template (partial) specialization.
1022 ClassKind,
1023
1024 /// Something that we consider a "variable":
1025 /// \li namespace scope variables and variable templates;
1026 /// \li static and non-static class data members and member templates;
1027 /// \li enumerators.
1028 VariableKind,
1029
1030 /// A C++ namespace.
1031 NamespaceKind,
1032
1033 /// A C++ typedef-name (a 'typedef' decl specifier or alias-declaration),
1034 /// see \c TypedefNameDecl.
1035 TypedefKind,
1036
1037 /// An enumeration or scoped enumeration.
1038 EnumKind,
1039
1040 ConceptKind
1041 };
1042
1043 /// What kind of template specialization \c CommentDecl is.
1044 enum TemplateDeclKind {
1045 NotTemplate,
1046 Template,
1047 TemplateSpecialization,
1048 TemplatePartialSpecialization
1049 };
1050
1051 /// If false, only \c CommentDecl is valid.
1052 LLVM_PREFERRED_TYPE(bool)
1053 unsigned IsFilled : 1;
1054
1055 /// Simplified kind of \c CommentDecl, see \c DeclKind enum.
1056 LLVM_PREFERRED_TYPE(DeclKind)
1057 unsigned Kind : 3;
1058
1059 /// Is \c CommentDecl a template declaration.
1060 LLVM_PREFERRED_TYPE(TemplateDeclKind)
1061 unsigned TemplateKind : 2;
1062
1063 /// Is \c CommentDecl an ObjCMethodDecl.
1064 LLVM_PREFERRED_TYPE(bool)
1065 unsigned IsObjCMethod : 1;
1066
1067 /// Is \c CommentDecl a non-static member function of C++ class or
1068 /// instance method of ObjC class.
1069 /// Can be true only if \c IsFunctionDecl is true.
1070 LLVM_PREFERRED_TYPE(bool)
1071 unsigned IsInstanceMethod : 1;
1072
1073 /// Is \c CommentDecl a static member function of C++ class or
1074 /// class method of ObjC class.
1075 /// Can be true only if \c IsFunctionDecl is true.
1076 LLVM_PREFERRED_TYPE(bool)
1077 unsigned IsClassMethod : 1;
1078
1079 /// Is \c CommentDecl something we consider a "function" that's variadic.
1080 LLVM_PREFERRED_TYPE(bool)
1081 unsigned IsVariadic : 1;
1082
1083 void fill();
1084
1085 DeclKind getKind() const LLVM_READONLY {
1086 return static_cast<DeclKind>(Kind);
1087 }
1088
1089 TemplateDeclKind getTemplateKind() const LLVM_READONLY {
1090 return static_cast<TemplateDeclKind>(TemplateKind);
1091 }
1092
1093 bool involvesFunctionType() const { return !ReturnType.isNull(); }
1094};
1095
1096/// A full comment attached to a declaration, contains block content.
1097class FullComment : public Comment {
1098 ArrayRef<BlockContentComment *> Blocks;
1099 DeclInfo *ThisDeclInfo;
1100
1101public:
1102 FullComment(ArrayRef<BlockContentComment *> Blocks, DeclInfo *D)
1103 : Comment(CommentKind::FullComment, SourceLocation(), SourceLocation()),
1104 Blocks(Blocks), ThisDeclInfo(D) {
1105 if (Blocks.empty())
1106 return;
1107
1108 setSourceRange(
1109 SourceRange(Blocks.front()->getBeginLoc(), Blocks.back()->getEndLoc()));
1110 setLocation(Blocks.front()->getBeginLoc());
1111 }
1112
1113 static bool classof(const Comment *C) {
1114 return C->getCommentKind() == CommentKind::FullComment;
1115 }
1116
1117 child_iterator child_begin() const {
1118 return reinterpret_cast<child_iterator>(Blocks.begin());
1119 }
1120
1121 child_iterator child_end() const {
1122 return reinterpret_cast<child_iterator>(Blocks.end());
1123 }
1124
1125 const Decl *getDecl() const LLVM_READONLY {
1126 return ThisDeclInfo->CommentDecl;
1127 }
1128
1129 const DeclInfo *getDeclInfo() const LLVM_READONLY {
1130 if (!ThisDeclInfo->IsFilled)
1131 ThisDeclInfo->fill();
1132 return ThisDeclInfo;
1133 }
1134
1135 ArrayRef<BlockContentComment *> getBlocks() const { return Blocks; }
1136
1137};
1138} // end namespace comments
1139} // end namespace clang
1140
1141#endif
1142
1143