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