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