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