contrib/llvm/tools/clang/include/clang/AST/Comment.h

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