Home | History | Annotate | Download | only in AST 
      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
    223