contrib/llvm-project/clang/include/clang/AST/Comment.h

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