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