CommentSema.h revision 263508 
1169695Skan//===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===//
2169695Skan//
3169695Skan//                     The LLVM Compiler Infrastructure
4169695Skan//
5169695Skan// This file is distributed under the University of Illinois Open Source
6169695Skan// License. See LICENSE.TXT for details.
7169695Skan//
8169695Skan//===----------------------------------------------------------------------===//
9169695Skan//
10169695Skan//  This file defines the semantic analysis class for Doxygen comments.
11169695Skan//
12169695Skan//===----------------------------------------------------------------------===//
13169695Skan
14169695Skan#ifndef LLVM_CLANG_AST_COMMENT_SEMA_H
15169695Skan#define LLVM_CLANG_AST_COMMENT_SEMA_H
16169695Skan
17169695Skan#include "clang/AST/Comment.h"
18169695Skan#include "clang/Basic/Diagnostic.h"
19169695Skan#include "clang/Basic/SourceLocation.h"
20169695Skan#include "llvm/ADT/ArrayRef.h"
21169695Skan#include "llvm/ADT/StringMap.h"
22169695Skan#include "llvm/ADT/StringRef.h"
23169695Skan#include "llvm/Support/Allocator.h"
24169695Skan
25169695Skannamespace clang {
26169695Skanclass Decl;
27169695Skanclass SourceMgr;
28169695Skanclass Preprocessor;
29169695Skan
30169695Skannamespace comments {
31169695Skanclass CommandTraits;
32169695Skan
33169695Skanclass Sema {
34169695Skan  Sema(const Sema &) LLVM_DELETED_FUNCTION;
35169695Skan  void operator=(const Sema &) LLVM_DELETED_FUNCTION;
36169695Skan
37169695Skan  /// Allocator for AST nodes.
38169695Skan  llvm::BumpPtrAllocator &Allocator;
39169695Skan
40169695Skan  /// Source manager for the comment being parsed.
41169695Skan  const SourceManager &SourceMgr;
42169695Skan
43169695Skan  DiagnosticsEngine &Diags;
44169695Skan
45169695Skan  CommandTraits &Traits;
46169695Skan
47169695Skan  const Preprocessor *PP;
48169695Skan
49169695Skan  /// Information about the declaration this comment is attached to.
50169695Skan  DeclInfo *ThisDeclInfo;
51169695Skan
52169695Skan  /// Comment AST nodes that correspond to parameter names in
53169695Skan  /// \c TemplateParameters.
54169695Skan  ///
55169695Skan  /// Contains a valid value if \c DeclInfo->IsFilled is true.
56169695Skan  llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
57169695Skan
58169695Skan  /// AST node for the \\brief command and its aliases.
59169695Skan  const BlockCommandComment *BriefCommand;
60169695Skan
61169695Skan  /// AST node for the \\headerfile command.
62169695Skan  const BlockCommandComment *HeaderfileCommand;
63169695Skan
64169695Skan  DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
65169695Skan    return Diags.Report(Loc, DiagID);
66169695Skan  }
67169695Skan
68169695Skan  /// A stack of HTML tags that are currently open (not matched with closing
69169695Skan  /// tags).
70169695Skan  SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
71169695Skan
72169695Skanpublic:
73169695Skan  Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
74169695Skan       DiagnosticsEngine &Diags, CommandTraits &Traits,
75169695Skan       const Preprocessor *PP);
76169695Skan
77169695Skan  void setDecl(const Decl *D);
78169695Skan
79169695Skan  /// Returns a copy of array, owned by Sema's allocator.
80169695Skan  template<typename T>
81169695Skan  ArrayRef<T> copyArray(ArrayRef<T> Source) {
82169695Skan    size_t Size = Source.size();
83169695Skan    if (Size != 0) {
84169695Skan      T *Mem = Allocator.Allocate<T>(Size);
85169695Skan      std::uninitialized_copy(Source.begin(), Source.end(), Mem);
86169695Skan      return llvm::makeArrayRef(Mem, Size);
87169695Skan    } else
88169695Skan      return llvm::makeArrayRef(static_cast<T *>(NULL), 0);
89169695Skan  }
90169695Skan
91169695Skan  ParagraphComment *actOnParagraphComment(
92169695Skan      ArrayRef<InlineContentComment *> Content);
93169695Skan
94169695Skan  BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
95169695Skan                                              SourceLocation LocEnd,
96169695Skan                                              unsigned CommandID,
97                                              CommandMarkerKind CommandMarker);
98
99  void actOnBlockCommandArgs(BlockCommandComment *Command,
100                             ArrayRef<BlockCommandComment::Argument> Args);
101
102  void actOnBlockCommandFinish(BlockCommandComment *Command,
103                               ParagraphComment *Paragraph);
104
105  ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
106                                              SourceLocation LocEnd,
107                                              unsigned CommandID,
108                                              CommandMarkerKind CommandMarker);
109
110  void actOnParamCommandDirectionArg(ParamCommandComment *Command,
111                                     SourceLocation ArgLocBegin,
112                                     SourceLocation ArgLocEnd,
113                                     StringRef Arg);
114
115  void actOnParamCommandParamNameArg(ParamCommandComment *Command,
116                                     SourceLocation ArgLocBegin,
117                                     SourceLocation ArgLocEnd,
118                                     StringRef Arg);
119
120  void actOnParamCommandFinish(ParamCommandComment *Command,
121                               ParagraphComment *Paragraph);
122
123  TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
124                                                SourceLocation LocEnd,
125                                                unsigned CommandID,
126                                                CommandMarkerKind CommandMarker);
127
128  void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
129                                      SourceLocation ArgLocBegin,
130                                      SourceLocation ArgLocEnd,
131                                      StringRef Arg);
132
133  void actOnTParamCommandFinish(TParamCommandComment *Command,
134                                ParagraphComment *Paragraph);
135
136  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
137                                           SourceLocation CommandLocEnd,
138                                           unsigned CommandID);
139
140  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
141                                           SourceLocation CommandLocEnd,
142                                           unsigned CommandID,
143                                           SourceLocation ArgLocBegin,
144                                           SourceLocation ArgLocEnd,
145                                           StringRef Arg);
146
147  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
148                                            SourceLocation LocEnd,
149                                            StringRef CommandName);
150
151  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
152                                            SourceLocation LocEnd,
153                                            unsigned CommandID);
154
155  TextComment *actOnText(SourceLocation LocBegin,
156                         SourceLocation LocEnd,
157                         StringRef Text);
158
159  VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
160                                                unsigned CommandID);
161
162  VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
163                                                   StringRef Text);
164
165  void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
166                                SourceLocation CloseNameLocBegin,
167                                StringRef CloseName,
168                                ArrayRef<VerbatimBlockLineComment *> Lines);
169
170  VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
171                                         unsigned CommandID,
172                                         SourceLocation TextBegin,
173                                         StringRef Text);
174
175  HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
176                                              StringRef TagName);
177
178  void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
179                               ArrayRef<HTMLStartTagComment::Attribute> Attrs,
180                               SourceLocation GreaterLoc,
181                               bool IsSelfClosing);
182
183  HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
184                                     SourceLocation LocEnd,
185                                     StringRef TagName);
186
187  FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
188
189  void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
190
191  void checkReturnsCommand(const BlockCommandComment *Command);
192
193  /// Emit diagnostics about duplicate block commands that should be
194  /// used only once per comment, e.g., \\brief and \\returns.
195  void checkBlockCommandDuplicate(const BlockCommandComment *Command);
196
197  void checkDeprecatedCommand(const BlockCommandComment *Comment);
198
199  void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
200
201  void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
202
203  void checkContainerDecl(const BlockCommandComment *Comment);
204
205  /// Resolve parameter names to parameter indexes in function declaration.
206  /// Emit diagnostics about unknown parametrs.
207  void resolveParamCommandIndexes(const FullComment *FC);
208
209  bool isFunctionDecl();
210  bool isAnyFunctionDecl();
211
212  /// \returns \c true if declaration that this comment is attached to declares
213  /// a function pointer.
214  bool isFunctionPointerVarDecl();
215  bool isFunctionOrMethodVariadic();
216  bool isObjCMethodDecl();
217  bool isObjCPropertyDecl();
218  bool isTemplateOrSpecialization();
219  bool isRecordLikeDecl();
220  bool isClassOrStructDecl();
221  bool isUnionDecl();
222  bool isObjCInterfaceDecl();
223  bool isObjCProtocolDecl();
224  bool isClassTemplateDecl();
225  bool isFunctionTemplateDecl();
226
227  ArrayRef<const ParmVarDecl *> getParamVars();
228
229  /// Extract all important semantic information from
230  /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
231  void inspectThisDecl();
232
233  /// Returns index of a function parameter with a given name.
234  unsigned resolveParmVarReference(StringRef Name,
235                                   ArrayRef<const ParmVarDecl *> ParamVars);
236
237  /// Returns index of a function parameter with the name closest to a given
238  /// typo.
239  unsigned correctTypoInParmVarReference(StringRef Typo,
240                                         ArrayRef<const ParmVarDecl *> ParamVars);
241
242  bool resolveTParamReference(StringRef Name,
243                              const TemplateParameterList *TemplateParameters,
244                              SmallVectorImpl<unsigned> *Position);
245
246  StringRef correctTypoInTParamReference(
247                              StringRef Typo,
248                              const TemplateParameterList *TemplateParameters);
249
250  InlineCommandComment::RenderKind
251  getInlineCommandRenderKind(StringRef Name) const;
252};
253
254} // end namespace comments
255} // end namespace clang
256
257#endif
258
259