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

   1 //===--- RawCommentList.h - Classes for processing raw comments -*- 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 #ifndef LLVM_CLANG_AST_RAW_COMMENT_LIST_H
  11 #define LLVM_CLANG_AST_RAW_COMMENT_LIST_H
  12
  13 #include "clang/Basic/CommentOptions.h"
  14 #include "clang/Basic/SourceManager.h"
  15 #include "llvm/ADT/ArrayRef.h"
  16
  17 namespace clang {
  18
  19 class ASTContext;
  20 class ASTReader;
  21 class Decl;
  22 class Preprocessor;
  23
  24 namespace comments {
  25   class FullComment;
  26 } // end namespace comments
  27
  28 class RawComment {
  29 public:
  30   enum CommentKind {
  31     RCK_Invalid,      ///< Invalid comment
  32     RCK_OrdinaryBCPL, ///< Any normal BCPL comments
  33     RCK_OrdinaryC,    ///< Any normal C comment
  34     RCK_BCPLSlash,    ///< \code /// stuff \endcode
  35     RCK_BCPLExcl,     ///< \code //! stuff \endcode
  36     RCK_JavaDoc,      ///< \code /** stuff */ \endcode
  37     RCK_Qt,           ///< \code /*! stuff */ \endcode, also used by HeaderDoc
  38     RCK_Merged        ///< Two or more documentation comments merged together
  39   };
  40
  41   RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }
  42
  43   RawComment(const SourceManager &SourceMgr, SourceRange SR,
  44              bool Merged, bool ParseAllComments);
  45
  46   CommentKind getKind() const LLVM_READONLY {
  47     return (CommentKind) Kind;
  48   }
  49
  50   bool isInvalid() const LLVM_READONLY {
  51     return Kind == RCK_Invalid;
  52   }
  53
  54   bool isMerged() const LLVM_READONLY {
  55     return Kind == RCK_Merged;
  56   }
  57
  58   /// Is this comment attached to any declaration?
  59   bool isAttached() const LLVM_READONLY {
  60     return IsAttached;
  61   }
  62
  63   void setAttached() {
  64     IsAttached = true;
  65   }
  66
  67   /// Returns true if it is a comment that should be put after a member:
  68   /// \code ///< stuff \endcode
  69   /// \code //!< stuff \endcode
  70   /// \code /**< stuff */ \endcode
  71   /// \code /*!< stuff */ \endcode
  72   bool isTrailingComment() const LLVM_READONLY {
  73     assert(isDocumentation());
  74     return IsTrailingComment;
  75   }
  76
  77   /// Returns true if it is a probable typo:
  78   /// \code //< stuff \endcode
  79   /// \code /*< stuff */ \endcode
  80   bool isAlmostTrailingComment() const LLVM_READONLY {
  81     return IsAlmostTrailingComment;
  82   }
  83
  84   /// Returns true if this comment is not a documentation comment.
  85   bool isOrdinary() const LLVM_READONLY {
  86     return ((Kind == RCK_OrdinaryBCPL) || (Kind == RCK_OrdinaryC)) &&
  87         !ParseAllComments;
  88   }
  89
  90   /// Returns true if this comment any kind of a documentation comment.
  91   bool isDocumentation() const LLVM_READONLY {
  92     return !isInvalid() && !isOrdinary();
  93   }
  94
  95   /// Returns whether we are parsing all comments.
  96   bool isParseAllComments() const LLVM_READONLY {
  97     return ParseAllComments;
  98   }
  99
 100   /// Returns raw comment text with comment markers.
 101   StringRef getRawText(const SourceManager &SourceMgr) const {
 102     if (RawTextValid)
 103       return RawText;
 104
 105     RawText = getRawTextSlow(SourceMgr);
 106     RawTextValid = true;
 107     return RawText;
 108   }
 109
 110   SourceRange getSourceRange() const LLVM_READONLY {
 111     return Range;
 112   }
 113
 114   unsigned getBeginLine(const SourceManager &SM) const;
 115   unsigned getEndLine(const SourceManager &SM) const;
 116
 117   const char *getBriefText(const ASTContext &Context) const {
 118     if (BriefTextValid)
 119       return BriefText;
 120
 121     return extractBriefText(Context);
 122   }
 123
 124   /// Parse the comment, assuming it is attached to decl \c D.
 125   comments::FullComment *parse(const ASTContext &Context,
 126                                const Preprocessor *PP, const Decl *D) const;
 127
 128 private:
 129   SourceRange Range;
 130
 131   mutable StringRef RawText;
 132   mutable const char *BriefText;
 133
 134   mutable bool RawTextValid : 1;   ///< True if RawText is valid
 135   mutable bool BriefTextValid : 1; ///< True if BriefText is valid
 136
 137   unsigned Kind : 3;
 138
 139   /// True if comment is attached to a declaration in ASTContext.
 140   bool IsAttached : 1;
 141
 142   bool IsTrailingComment : 1;
 143   bool IsAlmostTrailingComment : 1;
 144
 145   /// When true, ordinary comments starting with "//" and "/*" will be
 146   /// considered as documentation comments.
 147   bool ParseAllComments : 1;
 148
 149   mutable bool BeginLineValid : 1; ///< True if BeginLine is valid
 150   mutable bool EndLineValid : 1;   ///< True if EndLine is valid
 151   mutable unsigned BeginLine;      ///< Cached line number
 152   mutable unsigned EndLine;        ///< Cached line number
 153
 154   /// \brief Constructor for AST deserialization.
 155   RawComment(SourceRange SR, CommentKind K, bool IsTrailingComment,
 156              bool IsAlmostTrailingComment,
 157              bool ParseAllComments) :
 158     Range(SR), RawTextValid(false), BriefTextValid(false), Kind(K),
 159     IsAttached(false), IsTrailingComment(IsTrailingComment),
 160     IsAlmostTrailingComment(IsAlmostTrailingComment),
 161     ParseAllComments(ParseAllComments),
 162     BeginLineValid(false), EndLineValid(false)
 163   { }
 164
 165   StringRef getRawTextSlow(const SourceManager &SourceMgr) const;
 166
 167   const char *extractBriefText(const ASTContext &Context) const;
 168
 169   friend class ASTReader;
 170 };
 171
 172 /// \brief Compare comments' source locations.
 173 template<>
 174 class BeforeThanCompare<RawComment> {
 175   const SourceManager &SM;
 176
 177 public:
 178   explicit BeforeThanCompare(const SourceManager &SM) : SM(SM) { }
 179
 180   bool operator()(const RawComment &LHS, const RawComment &RHS) {
 181     return SM.isBeforeInTranslationUnit(LHS.getSourceRange().getBegin(),
 182                                         RHS.getSourceRange().getBegin());
 183   }
 184
 185   bool operator()(const RawComment *LHS, const RawComment *RHS) {
 186     return operator()(*LHS, *RHS);
 187   }
 188 };
 189
 190 /// \brief This class represents all comments included in the translation unit,
 191 /// sorted in order of appearance in the translation unit.
 192 class RawCommentList {
 193 public:
 194   RawCommentList(SourceManager &SourceMgr) :
 195     SourceMgr(SourceMgr), OnlyWhitespaceSeen(true) { }
 196
 197   void addComment(const RawComment &RC, llvm::BumpPtrAllocator &Allocator);
 198
 199   ArrayRef<RawComment *> getComments() const {
 200     return Comments;
 201   }
 202
 203 private:
 204   SourceManager &SourceMgr;
 205   std::vector<RawComment *> Comments;
 206   SourceLocation PrevCommentEndLoc;
 207   bool OnlyWhitespaceSeen;
 208
 209   void addCommentsToFront(const std::vector<RawComment *> &C) {
 210     size_t OldSize = Comments.size();
 211     Comments.resize(C.size() + OldSize);
 212     std::copy_backward(Comments.begin(), Comments.begin() + OldSize,
 213                        Comments.end());
 214     std::copy(C.begin(), C.end(), Comments.begin());
 215   }
 216
 217   friend class ASTReader;
 218 };
 219
 220 } // end namespace clang
 221
 222 #endif