CommentSema.h revision 1952354bd376062c3ab3d328c0fc6c36530c9309 
1//===--- CommentSema.h - Doxygen comment semantic analysis ------*- 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//  This file defines the semantic analysis class for Doxygen comments.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_CLANG_AST_COMMENT_SEMA_H
15#define LLVM_CLANG_AST_COMMENT_SEMA_H
16
17#include "clang/Basic/Diagnostic.h"
18#include "clang/Basic/SourceLocation.h"
19#include "clang/AST/Comment.h"
20#include "llvm/ADT/ArrayRef.h"
21#include "llvm/ADT/StringRef.h"
22#include "llvm/ADT/StringMap.h"
23#include "llvm/Support/Allocator.h"
24
25namespace clang {
26class Decl;
27class SourceMgr;
28class Preprocessor;
29
30namespace comments {
31class CommandTraits;
32
33class Sema {
34  Sema(const Sema &) LLVM_DELETED_FUNCTION;
35  void operator=(const Sema &) LLVM_DELETED_FUNCTION;
36
37  /// Allocator for AST nodes.
38  llvm::BumpPtrAllocator &Allocator;
39
40  /// Source manager for the comment being parsed.
41  const SourceManager &SourceMgr;
42
43  DiagnosticsEngine &Diags;
44
45  CommandTraits &Traits;
46
47  const Preprocessor *PP;
48
49  /// Information about the declaration this comment is attached to.
50  DeclInfo *ThisDeclInfo;
51
52  /// Comment AST nodes that correspond to parameter names in
53  /// \c TemplateParameters.
54  ///
55  /// Contains a valid value if \c DeclInfo->IsFilled is true.
56  llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
57
58  /// AST node for the \\brief command and its aliases.
59  const BlockCommandComment *BriefCommand;
60
61  /// AST node for the \\returns command and its aliases.
62  const BlockCommandComment *ReturnsCommand;
63
64  DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
65    return Diags.Report(Loc, DiagID);
66  }
67
68  /// A stack of HTML tags that are currently open (not matched with closing
69  /// tags).
70  SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
71
72public:
73  Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
74       DiagnosticsEngine &Diags, CommandTraits &Traits,
75       const Preprocessor *PP);
76
77  void setDecl(const Decl *D);
78
79  /// Returns a copy of array, owned by Sema's allocator.
80  template<typename T>
81  ArrayRef<T> copyArray(ArrayRef<T> Source) {
82    size_t Size = Source.size();
83    if (Size != 0) {
84      T *Mem = Allocator.Allocate<T>(Size);
85      std::uninitialized_copy(Source.begin(), Source.end(), Mem);
86      return llvm::makeArrayRef(Mem, Size);
87    } else
88      return llvm::makeArrayRef(static_cast<T *>(NULL), 0);
89  }
90
91  ParagraphComment *actOnParagraphComment(
92      ArrayRef<InlineContentComment *> Content);
93
94  BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
95                                              SourceLocation LocEnd,
96                                              unsigned CommandID);
97
98  void actOnBlockCommandArgs(BlockCommandComment *Command,
99                             ArrayRef<BlockCommandComment::Argument> Args);
100
101  void actOnBlockCommandFinish(BlockCommandComment *Command,
102                               ParagraphComment *Paragraph);
103
104  ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
105                                              SourceLocation LocEnd,
106                                              unsigned CommandID);
107
108  void actOnParamCommandDirectionArg(ParamCommandComment *Command,
109                                     SourceLocation ArgLocBegin,
110                                     SourceLocation ArgLocEnd,
111                                     StringRef Arg);
112
113  void actOnParamCommandParamNameArg(ParamCommandComment *Command,
114                                     SourceLocation ArgLocBegin,
115                                     SourceLocation ArgLocEnd,
116                                     StringRef Arg);
117
118  void actOnParamCommandFinish(ParamCommandComment *Command,
119                               ParagraphComment *Paragraph);
120
121  TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
122                                                SourceLocation LocEnd,
123                                                unsigned CommandID);
124
125  void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
126                                      SourceLocation ArgLocBegin,
127                                      SourceLocation ArgLocEnd,
128                                      StringRef Arg);
129
130  void actOnTParamCommandFinish(TParamCommandComment *Command,
131                                ParagraphComment *Paragraph);
132
133  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
134                                           SourceLocation CommandLocEnd,
135                                           unsigned CommandID);
136
137  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
138                                           SourceLocation CommandLocEnd,
139                                           unsigned CommandID,
140                                           SourceLocation ArgLocBegin,
141                                           SourceLocation ArgLocEnd,
142                                           StringRef Arg);
143
144  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
145                                            SourceLocation LocEnd,
146                                            StringRef CommandName);
147
148  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
149                                            SourceLocation LocEnd,
150                                            unsigned CommandID);
151
152  TextComment *actOnText(SourceLocation LocBegin,
153                         SourceLocation LocEnd,
154                         StringRef Text);
155
156  VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
157                                                unsigned CommandID);
158
159  VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
160                                                   StringRef Text);
161
162  void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
163                                SourceLocation CloseNameLocBegin,
164                                StringRef CloseName,
165                                ArrayRef<VerbatimBlockLineComment *> Lines);
166
167  VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
168                                         unsigned CommandID,
169                                         SourceLocation TextBegin,
170                                         StringRef Text);
171
172  HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
173                                              StringRef TagName);
174
175  void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
176                               ArrayRef<HTMLStartTagComment::Attribute> Attrs,
177                               SourceLocation GreaterLoc,
178                               bool IsSelfClosing);
179
180  HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
181                                     SourceLocation LocEnd,
182                                     StringRef TagName);
183
184  FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
185
186  void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
187
188  void checkReturnsCommand(const BlockCommandComment *Command);
189
190  /// Emit diagnostics about duplicate block commands that should be
191  /// used only once per comment, e.g., \\brief and \\returns.
192  void checkBlockCommandDuplicate(const BlockCommandComment *Command);
193
194  void checkDeprecatedCommand(const BlockCommandComment *Comment);
195
196  /// Resolve parameter names to parameter indexes in function declaration.
197  /// Emit diagnostics about unknown parametrs.
198  void resolveParamCommandIndexes(const FullComment *FC);
199
200  bool isFunctionDecl();
201  bool isTemplateOrSpecialization();
202
203  ArrayRef<const ParmVarDecl *> getParamVars();
204
205  /// Extract all important semantic information from
206  /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
207  void inspectThisDecl();
208
209  /// Returns index of a function parameter with a given name.
210  unsigned resolveParmVarReference(StringRef Name,
211                                   ArrayRef<const ParmVarDecl *> ParamVars);
212
213  /// Returns index of a function parameter with the name closest to a given
214  /// typo.
215  unsigned correctTypoInParmVarReference(StringRef Typo,
216                                         ArrayRef<const ParmVarDecl *> ParamVars);
217
218  bool resolveTParamReference(StringRef Name,
219                              const TemplateParameterList *TemplateParameters,
220                              SmallVectorImpl<unsigned> *Position);
221
222  StringRef correctTypoInTParamReference(
223                              StringRef Typo,
224                              const TemplateParameterList *TemplateParameters);
225
226  InlineCommandComment::RenderKind
227  getInlineCommandRenderKind(StringRef Name) const;
228};
229
230} // end namespace comments
231} // end namespace clang
232
233#endif
234
235