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