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_RAWCOMMENTLIST_H
  11 #define LLVM_CLANG_AST_RAWCOMMENTLIST_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              const CommentOptions &CommentOpts, bool Merged);
  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     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 { return Range; }
 104   SourceLocation getLocStart() const LLVM_READONLY { return Range.getBegin(); }
 105   SourceLocation getLocEnd() const LLVM_READONLY { return Range.getEnd(); }
 106
 107   const char *getBriefText(const ASTContext &Context) const {
 108     if (BriefTextValid)
 109       return BriefText;
 110
 111     return extractBriefText(Context);
 112   }
 113
 114   /// Returns sanitized comment text, suitable for presentation in editor UIs.
 115   /// E.g. will transform:
 116   ///     // This is a long multiline comment.
 117   ///     //   Parts of it  might be indented.
 118   ///     /* The comments styles might be mixed. */
 119   ///  into
 120   ///     "This is a long multiline comment.\n"
 121   ///     "  Parts of it  might be indented.\n"
 122   ///     "The comments styles might be mixed."
 123   /// Also removes leading indentation and sanitizes some common cases:
 124   ///     /* This is a first line.
 125   ///      *   This is a second line. It is indented.
 126   ///      * This is a third line. */
 127   /// and
 128   ///     /* This is a first line.
 129   ///          This is a second line. It is indented.
 130   ///     This is a third line. */
 131   /// will both turn into:
 132   ///     "This is a first line.\n"
 133   ///     "  This is a second line. It is indented.\n"
 134   ///     "This is a third line."
 135   std::string getFormattedText(const SourceManager &SourceMgr,
 136                                DiagnosticsEngine &Diags) const;
 137
 138   /// Parse the comment, assuming it is attached to decl \c D.
 139   comments::FullComment *parse(const ASTContext &Context,
 140                                const Preprocessor *PP, const Decl *D) const;
 141
 142 private:
 143   SourceRange Range;
 144
 145   mutable StringRef RawText;
 146   mutable const char *BriefText;
 147
 148   mutable bool RawTextValid : 1;   ///< True if RawText is valid
 149   mutable bool BriefTextValid : 1; ///< True if BriefText is valid
 150
 151   unsigned Kind : 3;
 152
 153   /// True if comment is attached to a declaration in ASTContext.
 154   bool IsAttached : 1;
 155
 156   bool IsTrailingComment : 1;
 157   bool IsAlmostTrailingComment : 1;
 158
 159   /// Constructor for AST deserialization.
 160   RawComment(SourceRange SR, CommentKind K, bool IsTrailingComment,
 161              bool IsAlmostTrailingComment) :
 162     Range(SR), RawTextValid(false), BriefTextValid(false), Kind(K),
 163     IsAttached(false), IsTrailingComment(IsTrailingComment),
 164     IsAlmostTrailingComment(IsAlmostTrailingComment)
 165   { }
 166
 167   StringRef getRawTextSlow(const SourceManager &SourceMgr) const;
 168
 169   const char *extractBriefText(const ASTContext &Context) const;
 170
 171   friend class ASTReader;
 172 };
 173
 174 /// Compare comments' source locations.
 175 template<>
 176 class BeforeThanCompare<RawComment> {
 177   const SourceManager &SM;
 178
 179 public:
 180   explicit BeforeThanCompare(const SourceManager &SM) : SM(SM) { }
 181
 182   bool operator()(const RawComment &LHS, const RawComment &RHS) {
 183     return SM.isBeforeInTranslationUnit(LHS.getLocStart(), RHS.getLocStart());
 184   }
 185
 186   bool operator()(const RawComment *LHS, const RawComment *RHS) {
 187     return operator()(*LHS, *RHS);
 188   }
 189 };
 190
 191 /// This class represents all comments included in the translation unit,
 192 /// sorted in order of appearance in the translation unit.
 193 class RawCommentList {
 194 public:
 195   RawCommentList(SourceManager &SourceMgr) : SourceMgr(SourceMgr) {}
 196
 197   void addComment(const RawComment &RC, const CommentOptions &CommentOpts,
 198                   llvm::BumpPtrAllocator &Allocator);
 199
 200   ArrayRef<RawComment *> getComments() const {
 201     return Comments;
 202   }
 203
 204 private:
 205   SourceManager &SourceMgr;
 206   std::vector<RawComment *> Comments;
 207
 208   void addDeserializedComments(ArrayRef<RawComment *> DeserializedComments);
 209
 210   friend class ASTReader;
 211 };
 212
 213 } // end namespace clang
 214
 215 #endif