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 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 }
356 InlineCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
357 unsigned CommandID, InlineCommandRenderKind RK,
358 CommandMarkerKind CommandMarker, ArrayRef<Argument> Args)
359 : InlineContentComment(CommentKind::InlineCommandComment, LocBegin,
360 LocEnd),
361 Args(Args) {
362 InlineCommandCommentBits.RenderKind = llvm::to_underlying(E: RK);
363 InlineCommandCommentBits.CommandID = CommandID;
364 InlineCommandCommentBits.CommandMarker = llvm::to_underlying(E: CommandMarker);
365 }
366
367 static bool classof(const Comment *C) {
368 return C->getCommentKind() == CommentKind::InlineCommandComment;
369 }
370
371 child_iterator child_begin() const { return nullptr; }
372
373 child_iterator child_end() const { return nullptr; }
374
375 unsigned getCommandID() const {
376 return InlineCommandCommentBits.CommandID;
377 }
378
379 StringRef getCommandName(const CommandTraits &Traits) const {
380 return Traits.getCommandInfo(CommandID: getCommandID())->Name;
381 }
382
383 SourceRange getCommandNameRange() const {
384 return SourceRange(getBeginLoc().getLocWithOffset(Offset: -1), getEndLoc());
385 }
386
387 InlineCommandRenderKind getRenderKind() const {
388 return static_cast<InlineCommandRenderKind>(
389 InlineCommandCommentBits.RenderKind);
390 }
391
392 unsigned getNumArgs() const {
393 return Args.size();
394 }
395
396 StringRef getArgText(unsigned Idx) const {
397 return Args[Idx].Text;
398 }
399
400 SourceRange getArgRange(unsigned Idx) const {
401 return Args[Idx].Range;
402 }
403
404 CommandMarkerKind getCommandMarker() const {
405 return static_cast<CommandMarkerKind>(
406 InlineCommandCommentBits.CommandMarker);
407 }
408};
409
410/// Abstract class for opening and closing HTML tags. HTML tags are always
411/// treated as inline content (regardless HTML semantics).
412class HTMLTagComment : public InlineContentComment {
413protected:
414 StringRef TagName;
415 SourceRange TagNameRange;
416
417 HTMLTagComment(CommentKind K,
418 SourceLocation LocBegin,
419 SourceLocation LocEnd,
420 StringRef TagName,
421 SourceLocation TagNameBegin,
422 SourceLocation TagNameEnd) :
423 InlineContentComment(K, LocBegin, LocEnd),
424 TagName(TagName),
425 TagNameRange(TagNameBegin, TagNameEnd) {
426 setLocation(TagNameBegin);
427 HTMLTagCommentBits.IsMalformed = 0;
428 }
429
430public:
431 static bool classof(const Comment *C) {
432 return C->getCommentKind() >= CommentKind::FirstHTMLTagCommentConstant &&
433 C->getCommentKind() <= CommentKind::LastHTMLTagCommentConstant;
434 }
435
436 StringRef getTagName() const LLVM_READONLY { return TagName; }
437
438 SourceRange getTagNameSourceRange() const LLVM_READONLY {
439 SourceLocation L = getLocation();
440 return SourceRange(L.getLocWithOffset(Offset: 1),
441 L.getLocWithOffset(Offset: 1 + TagName.size()));
442 }
443
444 bool isMalformed() const {
445 return HTMLTagCommentBits.IsMalformed;
446 }
447
448 void setIsMalformed() {
449 HTMLTagCommentBits.IsMalformed = 1;
450 }
451};
452
453/// An opening HTML tag with attributes.
454class HTMLStartTagComment : public HTMLTagComment {
455public:
456 class Attribute {
457 public:
458 SourceLocation NameLocBegin;
459 StringRef Name;
460
461 SourceLocation EqualsLoc;
462
463 SourceRange ValueRange;
464 StringRef Value;
465
466 Attribute() { }
467
468 Attribute(SourceLocation NameLocBegin, StringRef Name)
469 : NameLocBegin(NameLocBegin), Name(Name), EqualsLoc(SourceLocation()) {}
470
471 Attribute(SourceLocation NameLocBegin, StringRef Name,
472 SourceLocation EqualsLoc, SourceRange ValueRange, StringRef Value)
473 : NameLocBegin(NameLocBegin), Name(Name), EqualsLoc(EqualsLoc),
474 ValueRange(ValueRange), Value(Value) {}
475
476 SourceLocation getNameLocEnd() const {
477 return NameLocBegin.getLocWithOffset(Offset: Name.size());
478 }
479
480 SourceRange getNameRange() const {
481 return SourceRange(NameLocBegin, getNameLocEnd());
482 }
483 };
484
485private:
486 ArrayRef<Attribute> Attributes;
487
488public:
489 HTMLStartTagComment(SourceLocation LocBegin, StringRef TagName)
490 : HTMLTagComment(CommentKind::HTMLStartTagComment, LocBegin,
491 LocBegin.getLocWithOffset(Offset: 1 + TagName.size()), TagName,
492 LocBegin.getLocWithOffset(Offset: 1),
493 LocBegin.getLocWithOffset(Offset: 1 + TagName.size())) {
494 HTMLStartTagCommentBits.IsSelfClosing = false;
495 }
496
497 static bool classof(const Comment *C) {
498 return C->getCommentKind() == CommentKind::HTMLStartTagComment;
499 }
500
501 child_iterator child_begin() const { return nullptr; }
502
503 child_iterator child_end() const { return nullptr; }
504
505 unsigned getNumAttrs() const {
506 return Attributes.size();
507 }
508
509 const Attribute &getAttr(unsigned Idx) const {
510 return Attributes[Idx];
511 }
512
513 void setAttrs(ArrayRef<Attribute> Attrs) {
514 Attributes = Attrs;
515 if (!Attrs.empty()) {
516 const Attribute &Attr = Attrs.back();
517 SourceLocation L = Attr.ValueRange.getEnd();
518 if (L.isValid())
519 Range.setEnd(L);
520 else {
521 Range.setEnd(Attr.getNameLocEnd());
522 }
523 }
524 }
525
526 void setGreaterLoc(SourceLocation GreaterLoc) {
527 Range.setEnd(GreaterLoc);
528 }
529
530 bool isSelfClosing() const {
531 return HTMLStartTagCommentBits.IsSelfClosing;
532 }
533
534 void setSelfClosing() {
535 HTMLStartTagCommentBits.IsSelfClosing = true;
536 }
537};
538
539/// A closing HTML tag.
540class HTMLEndTagComment : public HTMLTagComment {
541public:
542 HTMLEndTagComment(SourceLocation LocBegin, SourceLocation LocEnd,
543 StringRef TagName)
544 : HTMLTagComment(CommentKind::HTMLEndTagComment, LocBegin, LocEnd,
545 TagName, LocBegin.getLocWithOffset(Offset: 2),
546 LocBegin.getLocWithOffset(Offset: 2 + TagName.size())) {}
547
548 static bool classof(const Comment *C) {
549 return C->getCommentKind() == CommentKind::HTMLEndTagComment;
550 }
551
552 child_iterator child_begin() const { return nullptr; }
553
554 child_iterator child_end() const { return nullptr; }
555};
556
557/// Block content (contains inline content).
558/// Abstract class.
559class BlockContentComment : public Comment {
560protected:
561 BlockContentComment(CommentKind K,
562 SourceLocation LocBegin,
563 SourceLocation LocEnd) :
564 Comment(K, LocBegin, LocEnd)
565 { }
566
567public:
568 static bool classof(const Comment *C) {
569 return C->getCommentKind() >=
570 CommentKind::FirstBlockContentCommentConstant &&
571 C->getCommentKind() <= CommentKind::LastBlockContentCommentConstant;
572 }
573};
574
575/// A single paragraph that contains inline content.
576class ParagraphComment : public BlockContentComment {
577 ArrayRef<InlineContentComment *> Content;
578
579public:
580 ParagraphComment(ArrayRef<InlineContentComment *> Content)
581 : BlockContentComment(CommentKind::ParagraphComment, SourceLocation(),
582 SourceLocation()),
583 Content(Content) {
584 if (Content.empty()) {
585 ParagraphCommentBits.IsWhitespace = true;
586 ParagraphCommentBits.IsWhitespaceValid = true;
587 return;
588 }
589
590 ParagraphCommentBits.IsWhitespaceValid = false;
591
592 setSourceRange(SourceRange(Content.front()->getBeginLoc(),
593 Content.back()->getEndLoc()));
594 setLocation(Content.front()->getBeginLoc());
595 }
596
597 static bool classof(const Comment *C) {
598 return C->getCommentKind() == CommentKind::ParagraphComment;
599 }
600
601 child_iterator child_begin() const {
602 return reinterpret_cast<child_iterator>(Content.begin());
603 }
604
605 child_iterator child_end() const {
606 return reinterpret_cast<child_iterator>(Content.end());
607 }
608
609 bool isWhitespace() const {
610 if (ParagraphCommentBits.IsWhitespaceValid)
611 return ParagraphCommentBits.IsWhitespace;
612
613 ParagraphCommentBits.IsWhitespace = isWhitespaceNoCache();
614 ParagraphCommentBits.IsWhitespaceValid = true;
615 return ParagraphCommentBits.IsWhitespace;
616 }
617
618private:
619 bool isWhitespaceNoCache() const;
620};
621
622/// A command that has zero or more word-like arguments (number of word-like
623/// arguments depends on command name) and a paragraph as an argument
624/// (e. g., \\brief).
625class BlockCommandComment : public BlockContentComment {
626protected:
627 /// Word-like arguments.
628 ArrayRef<Argument> Args;
629
630 /// Paragraph argument.
631 ParagraphComment *Paragraph;
632
633 BlockCommandComment(CommentKind K,
634 SourceLocation LocBegin,
635 SourceLocation LocEnd,
636 unsigned CommandID,
637 CommandMarkerKind CommandMarker) :
638 BlockContentComment(K, LocBegin, LocEnd),
639 Paragraph(nullptr) {
640 setLocation(getCommandNameBeginLoc());
641 BlockCommandCommentBits.CommandID = CommandID;
642 BlockCommandCommentBits.CommandMarker = CommandMarker;
643 }
644
645public:
646 BlockCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
647 unsigned CommandID, CommandMarkerKind CommandMarker)
648 : BlockContentComment(CommentKind::BlockCommandComment, LocBegin, LocEnd),
649 Paragraph(nullptr) {
650 setLocation(getCommandNameBeginLoc());
651 BlockCommandCommentBits.CommandID = CommandID;
652 BlockCommandCommentBits.CommandMarker = CommandMarker;
653 }
654
655 static bool classof(const Comment *C) {
656 return C->getCommentKind() >=
657 CommentKind::FirstBlockCommandCommentConstant &&
658 C->getCommentKind() <= CommentKind::LastBlockCommandCommentConstant;
659 }
660
661 child_iterator child_begin() const {
662 return reinterpret_cast<child_iterator>(&Paragraph);
663 }
664
665 child_iterator child_end() const {
666 return reinterpret_cast<child_iterator>(&Paragraph + 1);
667 }
668
669 unsigned getCommandID() const {
670 return BlockCommandCommentBits.CommandID;
671 }
672
673 StringRef getCommandName(const CommandTraits &Traits) const {
674 return Traits.getCommandInfo(CommandID: getCommandID())->Name;
675 }
676
677 SourceLocation getCommandNameBeginLoc() const {
678 return getBeginLoc().getLocWithOffset(Offset: 1);
679 }
680
681 SourceRange getCommandNameRange(const CommandTraits &Traits) const {
682 StringRef Name = getCommandName(Traits);
683 return SourceRange(getCommandNameBeginLoc(),
684 getBeginLoc().getLocWithOffset(Offset: 1 + Name.size()));
685 }
686
687 unsigned getNumArgs() const {
688 return Args.size();
689 }
690
691 StringRef getArgText(unsigned Idx) const {
692 return Args[Idx].Text;
693 }
694
695 SourceRange getArgRange(unsigned Idx) const {
696 return Args[Idx].Range;
697 }
698
699 void setArgs(ArrayRef<Argument> A) {
700 Args = A;
701 if (Args.size() > 0) {
702 SourceLocation NewLocEnd = Args.back().Range.getEnd();
703 if (NewLocEnd.isValid())
704 setSourceRange(SourceRange(getBeginLoc(), NewLocEnd));
705 }
706 }
707
708 ParagraphComment *getParagraph() const LLVM_READONLY {
709 return Paragraph;
710 }
711
712 bool hasNonWhitespaceParagraph() const {
713 return Paragraph && !Paragraph->isWhitespace();
714 }
715
716 void setParagraph(ParagraphComment *PC) {
717 Paragraph = PC;
718 SourceLocation NewLocEnd = PC->getEndLoc();
719 if (NewLocEnd.isValid())
720 setSourceRange(SourceRange(getBeginLoc(), NewLocEnd));
721 }
722
723 CommandMarkerKind getCommandMarker() const LLVM_READONLY {
724 return static_cast<CommandMarkerKind>(
725 BlockCommandCommentBits.CommandMarker);
726 }
727};
728
729enum class ParamCommandPassDirection { In, Out, InOut };
730
731/// Doxygen \\param command.
732class ParamCommandComment : public BlockCommandComment {
733private:
734 /// Parameter index in the function declaration.
735 unsigned ParamIndex;
736
737public:
738 enum : unsigned {
739 InvalidParamIndex = ~0U,
740 VarArgParamIndex = ~0U/*InvalidParamIndex*/ - 1U
741 };
742
743 ParamCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
744 unsigned CommandID, CommandMarkerKind CommandMarker)
745 : BlockCommandComment(CommentKind::ParamCommandComment, LocBegin, LocEnd,
746 CommandID, CommandMarker),
747 ParamIndex(InvalidParamIndex) {
748 ParamCommandCommentBits.Direction =
749 llvm::to_underlying(E: ParamCommandPassDirection::In);
750 ParamCommandCommentBits.IsDirectionExplicit = false;
751 }
752
753 static bool classof(const Comment *C) {
754 return C->getCommentKind() == CommentKind::ParamCommandComment;
755 }
756
757 static const char *getDirectionAsString(ParamCommandPassDirection D);
758
759 ParamCommandPassDirection getDirection() const LLVM_READONLY {
760 return static_cast<ParamCommandPassDirection>(
761 ParamCommandCommentBits.Direction);
762 }
763
764 bool isDirectionExplicit() const LLVM_READONLY {
765 return ParamCommandCommentBits.IsDirectionExplicit;
766 }
767
768 void setDirection(ParamCommandPassDirection Direction, bool Explicit) {
769 ParamCommandCommentBits.Direction = llvm::to_underlying(E: Direction);
770 ParamCommandCommentBits.IsDirectionExplicit = Explicit;
771 }
772
773 bool hasParamName() const {
774 return getNumArgs() > 0;
775 }
776
777 StringRef getParamName(const FullComment *FC) const;
778
779 StringRef getParamNameAsWritten() const {
780 return Args[0].Text;
781 }
782
783 SourceRange getParamNameRange() const {
784 return Args[0].Range;
785 }
786
787 bool isParamIndexValid() const LLVM_READONLY {
788 return ParamIndex != InvalidParamIndex;
789 }
790
791 bool isVarArgParam() const LLVM_READONLY {
792 return ParamIndex == VarArgParamIndex;
793 }
794
795 void setIsVarArgParam() {
796 ParamIndex = VarArgParamIndex;
797 assert(isParamIndexValid());
798 }
799
800 unsigned getParamIndex() const LLVM_READONLY {
801 assert(isParamIndexValid());
802 assert(!isVarArgParam());
803 return ParamIndex;
804 }
805
806 void setParamIndex(unsigned Index) {
807 ParamIndex = Index;
808 assert(isParamIndexValid());
809 assert(!isVarArgParam());
810 }
811};
812
813/// Doxygen \\tparam command, describes a template parameter.
814class TParamCommandComment : public BlockCommandComment {
815private:
816 /// If this template parameter name was resolved (found in template parameter
817 /// list), then this stores a list of position indexes in all template
818 /// parameter lists.
819 ///
820 /// For example:
821 /// \verbatim
822 /// template<typename C, template<typename T> class TT>
823 /// void test(TT<int> aaa);
824 /// \endverbatim
825 /// For C: Position = { 0 }
826 /// For TT: Position = { 1 }
827 /// For T: Position = { 1, 0 }
828 ArrayRef<unsigned> Position;
829
830public:
831 TParamCommandComment(SourceLocation LocBegin, SourceLocation LocEnd,
832 unsigned CommandID, CommandMarkerKind CommandMarker)
833 : BlockCommandComment(CommentKind::TParamCommandComment, LocBegin, LocEnd,
834 CommandID, CommandMarker) {}
835
836 static bool classof(const Comment *C) {
837 return C->getCommentKind() == CommentKind::TParamCommandComment;
838 }
839
840 bool hasParamName() const {
841 return getNumArgs() > 0;
842 }
843
844 StringRef getParamName(const FullComment *FC) const;
845
846 StringRef getParamNameAsWritten() const {
847 return Args[0].Text;
848 }
849
850 SourceRange getParamNameRange() const {
851 return Args[0].Range;
852 }
853
854 bool isPositionValid() const LLVM_READONLY {
855 return !Position.empty();
856 }
857
858 unsigned getDepth() const {
859 assert(isPositionValid());
860 return Position.size();
861 }
862
863 unsigned getIndex(unsigned Depth) const {
864 assert(isPositionValid());
865 return Position[Depth];
866 }
867
868 void setPosition(ArrayRef<unsigned> NewPosition) {
869 Position = NewPosition;
870 assert(isPositionValid());
871 }
872};
873
874/// A line of text contained in a verbatim block.
875class VerbatimBlockLineComment : public Comment {
876 StringRef Text;
877
878public:
879 VerbatimBlockLineComment(SourceLocation LocBegin, StringRef Text)
880 : Comment(CommentKind::VerbatimBlockLineComment, LocBegin,
881 LocBegin.getLocWithOffset(Offset: Text.size())),
882 Text(Text) {}
883
884 static bool classof(const Comment *C) {
885 return C->getCommentKind() == CommentKind::VerbatimBlockLineComment;
886 }
887
888 child_iterator child_begin() const { return nullptr; }
889
890 child_iterator child_end() const { return nullptr; }
891
892 StringRef getText() const LLVM_READONLY {
893 return Text;
894 }
895};
896
897/// A verbatim block command (e. g., preformatted code). Verbatim block has an
898/// opening and a closing command and contains multiple lines of text
899/// (VerbatimBlockLineComment nodes).
900class VerbatimBlockComment : public BlockCommandComment {
901protected:
902 StringRef CloseName;
903 SourceLocation CloseNameLocBegin;
904 ArrayRef<VerbatimBlockLineComment *> Lines;
905
906public:
907 VerbatimBlockComment(SourceLocation LocBegin, SourceLocation LocEnd,
908 unsigned CommandID)
909 : BlockCommandComment(CommentKind::VerbatimBlockComment, LocBegin, LocEnd,
910 CommandID,
911 CMK_At) // FIXME: improve source fidelity.
912 {}
913
914 static bool classof(const Comment *C) {
915 return C->getCommentKind() == CommentKind::VerbatimBlockComment;
916 }
917
918 child_iterator child_begin() const {
919 return reinterpret_cast<child_iterator>(Lines.begin());
920 }
921
922 child_iterator child_end() const {
923 return reinterpret_cast<child_iterator>(Lines.end());
924 }
925
926 void setCloseName(StringRef Name, SourceLocation LocBegin) {
927 CloseName = Name;
928 CloseNameLocBegin = LocBegin;
929 }
930
931 void setLines(ArrayRef<VerbatimBlockLineComment *> L) {
932 Lines = L;
933 }
934
935 StringRef getCloseName() const {
936 return CloseName;
937 }
938
939 unsigned getNumLines() const {
940 return Lines.size();
941 }
942
943 StringRef getText(unsigned LineIdx) const {
944 return Lines[LineIdx]->getText();
945 }
946};
947
948/// A verbatim line command. Verbatim line has an opening command, a single
949/// line of text (up to the newline after the opening command) and has no
950/// closing command.
951class VerbatimLineComment : public BlockCommandComment {
952protected:
953 StringRef Text;
954 SourceLocation TextBegin;
955
956public:
957 VerbatimLineComment(SourceLocation LocBegin, SourceLocation LocEnd,
958 unsigned CommandID, SourceLocation TextBegin,
959 StringRef Text)
960 : BlockCommandComment(CommentKind::VerbatimLineComment, LocBegin, LocEnd,
961 CommandID,
962 CMK_At), // FIXME: improve source fidelity.
963 Text(Text), TextBegin(TextBegin) {}
964
965 static bool classof(const Comment *C) {
966 return C->getCommentKind() == CommentKind::VerbatimLineComment;
967 }
968
969 child_iterator child_begin() const { return nullptr; }
970
971 child_iterator child_end() const { return nullptr; }
972
973 StringRef getText() const {
974 return Text;
975 }
976
977 SourceRange getTextRange() const {
978 return SourceRange(TextBegin, getEndLoc());
979 }
980};
981
982/// Information about the declaration, useful to clients of FullComment.
983struct DeclInfo {
984 /// Declaration the comment is actually attached to (in the source).
985 /// Should not be NULL.
986 const Decl *CommentDecl;
987
988 /// CurrentDecl is the declaration with which the FullComment is associated.
989 ///
990 /// It can be different from \c CommentDecl. It happens when we decide
991 /// that the comment originally attached to \c CommentDecl is fine for
992 /// \c CurrentDecl too (for example, for a redeclaration or an overrider of
993 /// \c CommentDecl).
994 ///
995 /// The information in the DeclInfo corresponds to CurrentDecl.
996 const Decl *CurrentDecl;
997
998 /// Parameters that can be referenced by \\param if \c CommentDecl is something
999 /// that we consider a "function".
1000 ArrayRef<const ParmVarDecl *> ParamVars;
1001
1002 /// Function return type if \c CommentDecl is something that we consider
1003 /// a "function".
1004 QualType ReturnType;
1005
1006 /// Template parameters that can be referenced by \\tparam if \c CommentDecl is
1007 /// a template (\c IsTemplateDecl or \c IsTemplatePartialSpecialization is
1008 /// true).
1009 const TemplateParameterList *TemplateParameters;
1010
1011 /// A simplified description of \c CommentDecl kind that should be good enough
1012 /// for documentation rendering purposes.
1013 enum DeclKind {
1014 /// Everything else not explicitly mentioned below.
1015 OtherKind,
1016
1017 /// Something that we consider a "function":
1018 /// \li function,
1019 /// \li function template,
1020 /// \li function template specialization,
1021 /// \li member function,
1022 /// \li member function template,
1023 /// \li member function template specialization,
1024 /// \li ObjC method,
1025 FunctionKind,
1026
1027 /// Something that we consider a "class":
1028 /// \li class/struct,
1029 /// \li class template,
1030 /// \li class template (partial) specialization.
1031 ClassKind,
1032
1033 /// Something that we consider a "variable":
1034 /// \li namespace scope variables and variable templates;
1035 /// \li static and non-static class data members and member templates;
1036 /// \li enumerators.
1037 VariableKind,
1038
1039 /// A C++ namespace.
1040 NamespaceKind,
1041
1042 /// A C++ typedef-name (a 'typedef' decl specifier or alias-declaration),
1043 /// see \c TypedefNameDecl.
1044 TypedefKind,
1045
1046 /// An enumeration or scoped enumeration.
1047 EnumKind
1048 };
1049
1050 /// What kind of template specialization \c CommentDecl is.
1051 enum TemplateDeclKind {
1052 NotTemplate,
1053 Template,
1054 TemplateSpecialization,
1055 TemplatePartialSpecialization
1056 };
1057
1058 /// If false, only \c CommentDecl is valid.
1059 LLVM_PREFERRED_TYPE(bool)
1060 unsigned IsFilled : 1;
1061
1062 /// Simplified kind of \c CommentDecl, see \c DeclKind enum.
1063 LLVM_PREFERRED_TYPE(DeclKind)
1064 unsigned Kind : 3;
1065
1066 /// Is \c CommentDecl a template declaration.
1067 LLVM_PREFERRED_TYPE(TemplateDeclKind)
1068 unsigned TemplateKind : 2;
1069
1070 /// Is \c CommentDecl an ObjCMethodDecl.
1071 LLVM_PREFERRED_TYPE(bool)
1072 unsigned IsObjCMethod : 1;
1073
1074 /// Is \c CommentDecl a non-static member function of C++ class or
1075 /// instance method of ObjC class.
1076 /// Can be true only if \c IsFunctionDecl is true.
1077 LLVM_PREFERRED_TYPE(bool)
1078 unsigned IsInstanceMethod : 1;
1079
1080 /// Is \c CommentDecl a static member function of C++ class or
1081 /// class method of ObjC class.
1082 /// Can be true only if \c IsFunctionDecl is true.
1083 LLVM_PREFERRED_TYPE(bool)
1084 unsigned IsClassMethod : 1;
1085
1086 /// Is \c CommentDecl something we consider a "function" that's variadic.
1087 LLVM_PREFERRED_TYPE(bool)
1088 unsigned IsVariadic : 1;
1089
1090 void fill();
1091
1092 DeclKind getKind() const LLVM_READONLY {
1093 return static_cast<DeclKind>(Kind);
1094 }
1095
1096 TemplateDeclKind getTemplateKind() const LLVM_READONLY {
1097 return static_cast<TemplateDeclKind>(TemplateKind);
1098 }
1099
1100 bool involvesFunctionType() const { return !ReturnType.isNull(); }
1101};
1102
1103/// A full comment attached to a declaration, contains block content.
1104class FullComment : public Comment {
1105 ArrayRef<BlockContentComment *> Blocks;
1106 DeclInfo *ThisDeclInfo;
1107
1108public:
1109 FullComment(ArrayRef<BlockContentComment *> Blocks, DeclInfo *D)
1110 : Comment(CommentKind::FullComment, SourceLocation(), SourceLocation()),
1111 Blocks(Blocks), ThisDeclInfo(D) {
1112 if (Blocks.empty())
1113 return;
1114
1115 setSourceRange(
1116 SourceRange(Blocks.front()->getBeginLoc(), Blocks.back()->getEndLoc()));
1117 setLocation(Blocks.front()->getBeginLoc());
1118 }
1119
1120 static bool classof(const Comment *C) {
1121 return C->getCommentKind() == CommentKind::FullComment;
1122 }
1123
1124 child_iterator child_begin() const {
1125 return reinterpret_cast<child_iterator>(Blocks.begin());
1126 }
1127
1128 child_iterator child_end() const {
1129 return reinterpret_cast<child_iterator>(Blocks.end());
1130 }
1131
1132 const Decl *getDecl() const LLVM_READONLY {
1133 return ThisDeclInfo->CommentDecl;
1134 }
1135
1136 const DeclInfo *getDeclInfo() const LLVM_READONLY {
1137 if (!ThisDeclInfo->IsFilled)
1138 ThisDeclInfo->fill();
1139 return ThisDeclInfo;
1140 }
1141
1142 ArrayRef<BlockContentComment *> getBlocks() const { return Blocks; }
1143
1144};
1145} // end namespace comments
1146} // end namespace clang
1147
1148#endif
1149
1150