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 
RawComment()41   RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }
42 
43   RawComment(const SourceManager &SourceMgr, SourceRange SR,
44              const CommentOptions &CommentOpts, bool Merged);
45 
getKind()46   CommentKind getKind() const LLVM_READONLY {
47     return (CommentKind) Kind;
48   }
49 
isInvalid()50   bool isInvalid() const LLVM_READONLY {
51     return Kind == RCK_Invalid;
52   }
53 
isMerged()54   bool isMerged() const LLVM_READONLY {
55     return Kind == RCK_Merged;
56   }
57 
58   /// Is this comment attached to any declaration?
isAttached()59   bool isAttached() const LLVM_READONLY {
60     return IsAttached;
61   }
62 
setAttached()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
isTrailingComment()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
isAlmostTrailingComment()79   bool isAlmostTrailingComment() const LLVM_READONLY {
80     return IsAlmostTrailingComment;
81   }
82 
83   /// Returns true if this comment is not a documentation comment.
isOrdinary()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.
isDocumentation()89   bool isDocumentation() const LLVM_READONLY {
90     return !isInvalid() && !isOrdinary();
91   }
92 
93   /// Returns raw comment text with comment markers.
getRawText(const SourceManager & SourceMgr)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 
getSourceRange()103   SourceRange getSourceRange() const LLVM_READONLY { return Range; }
getBeginLoc()104   SourceLocation getBeginLoc() const LLVM_READONLY { return Range.getBegin(); }
getEndLoc()105   SourceLocation getEndLoc() const LLVM_READONLY { return Range.getEnd(); }
106 
getBriefText(const ASTContext & Context)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.
RawComment(SourceRange SR,CommentKind K,bool IsTrailingComment,bool IsAlmostTrailingComment)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:
BeforeThanCompare(const SourceManager & SM)180   explicit BeforeThanCompare(const SourceManager &SM) : SM(SM) { }
181 
operator()182   bool operator()(const RawComment &LHS, const RawComment &RHS) {
183     return SM.isBeforeInTranslationUnit(LHS.getBeginLoc(), RHS.getBeginLoc());
184   }
185 
operator()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:
RawCommentList(SourceManager & SourceMgr)195   RawCommentList(SourceManager &SourceMgr) : SourceMgr(SourceMgr) {}
196 
197   void addComment(const RawComment &RC, const CommentOptions &CommentOpts,
198                   llvm::BumpPtrAllocator &Allocator);
199 
getComments()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
216