CommentSema.h revision 9443c57150e870e308406e1e4e6d9d64712b417e 
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 {
30
31class Sema {
32  Sema(const Sema&);           // DO NOT IMPLEMENT
33  void operator=(const Sema&); // DO NOT IMPLEMENT
34
35  /// Allocator for AST nodes.
36  llvm::BumpPtrAllocator &Allocator;
37
38  /// Source manager for the comment being parsed.
39  const SourceManager &SourceMgr;
40
41  DiagnosticsEngine &Diags;
42
43  /// Information about the declaration this comment is attached to.
44  DeclInfo *ThisDeclInfo;
45
46  /// Comment AST nodes that correspond to \c ParamVars for which we have
47  /// found a \\param command or NULL if no documentation was found so far.
48  ///
49  /// Has correct size and contains valid values if \c DeclInfo->IsFilled is
50  /// true.
51  llvm::SmallVector<ParamCommandComment *, 8> ParamVarDocs;
52
53  /// Comment AST nodes that correspond to parameter names in
54  /// \c TemplateParameters.
55  ///
56  /// Contains a valid value if \c DeclInfo->IsFilled is true.
57  llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
58
59  /// AST node for the \\brief command and its aliases.
60  const BlockCommandComment *BriefCommand;
61
62  /// AST node for the \\returns command and its aliases.
63  const BlockCommandComment *ReturnsCommand;
64
65  DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
66    return Diags.Report(Loc, DiagID);
67  }
68
69  /// A stack of HTML tags that are currently open (not matched with closing
70  /// tags).
71  SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
72
73public:
74  Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
75       DiagnosticsEngine &Diags);
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                                              StringRef Name);
97
98  BlockCommandComment *actOnBlockCommandArgs(
99                              BlockCommandComment *Command,
100                              ArrayRef<BlockCommandComment::Argument> Args);
101
102  BlockCommandComment *actOnBlockCommandFinish(BlockCommandComment *Command,
103                                               ParagraphComment *Paragraph);
104
105  ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
106                                              SourceLocation LocEnd,
107                                              StringRef Name);
108
109  ParamCommandComment *actOnParamCommandDirectionArg(
110                                            ParamCommandComment *Command,
111                                            SourceLocation ArgLocBegin,
112                                            SourceLocation ArgLocEnd,
113                                            StringRef Arg);
114
115  ParamCommandComment *actOnParamCommandParamNameArg(
116                                            ParamCommandComment *Command,
117                                            SourceLocation ArgLocBegin,
118                                            SourceLocation ArgLocEnd,
119                                            StringRef Arg);
120
121  ParamCommandComment *actOnParamCommandFinish(ParamCommandComment *Command,
122                                               ParagraphComment *Paragraph);
123
124  TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
125                                                SourceLocation LocEnd,
126                                                StringRef Name);
127
128  TParamCommandComment *actOnTParamCommandParamNameArg(
129                                            TParamCommandComment *Command,
130                                            SourceLocation ArgLocBegin,
131                                            SourceLocation ArgLocEnd,
132                                            StringRef Arg);
133
134  TParamCommandComment *actOnTParamCommandFinish(TParamCommandComment *Command,
135                                                 ParagraphComment *Paragraph);
136
137  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
138                                           SourceLocation CommandLocEnd,
139                                           StringRef CommandName);
140
141  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
142                                           SourceLocation CommandLocEnd,
143                                           StringRef CommandName,
144                                           SourceLocation ArgLocBegin,
145                                           SourceLocation ArgLocEnd,
146                                           StringRef Arg);
147
148  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
149                                            SourceLocation LocEnd,
150                                            StringRef Name);
151
152  TextComment *actOnText(SourceLocation LocBegin,
153                         SourceLocation LocEnd,
154                         StringRef Text);
155
156  VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
157                                                StringRef Name);
158
159  VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
160                                                   StringRef Text);
161
162  VerbatimBlockComment *actOnVerbatimBlockFinish(
163                              VerbatimBlockComment *Block,
164                              SourceLocation CloseNameLocBegin,
165                              StringRef CloseName,
166                              ArrayRef<VerbatimBlockLineComment *> Lines);
167
168  VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
169                                         StringRef Name,
170                                         SourceLocation TextBegin,
171                                         StringRef Text);
172
173  HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
174                                              StringRef TagName);
175
176  HTMLStartTagComment *actOnHTMLStartTagFinish(
177                              HTMLStartTagComment *Tag,
178                              ArrayRef<HTMLStartTagComment::Attribute> Attrs,
179                              SourceLocation GreaterLoc,
180                              bool IsSelfClosing);
181
182  HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
183                                     SourceLocation LocEnd,
184                                     StringRef TagName);
185
186  FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
187
188  void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
189
190  void checkReturnsCommand(const BlockCommandComment *Command);
191
192  /// Emit diagnostics about duplicate block commands that should be
193  /// used only once per comment, e.g., \\brief and \\returns.
194  void checkBlockCommandDuplicate(const BlockCommandComment *Command);
195
196  bool isFunctionDecl();
197  bool isTemplateDecl();
198
199  ArrayRef<const ParmVarDecl *> getParamVars();
200
201  /// Extract all important semantic information from
202  /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
203  void inspectThisDecl();
204
205  /// Returns index of a function parameter with a given name.
206  unsigned resolveParmVarReference(StringRef Name,
207                                   ArrayRef<const ParmVarDecl *> ParamVars);
208
209  /// Returns index of a function parameter with the name closest to a given
210  /// typo.
211  unsigned correctTypoInParmVarReference(StringRef Typo,
212                                         ArrayRef<const ParmVarDecl *> ParamVars);
213
214  bool resolveTParamReference(StringRef Name,
215                              const TemplateParameterList *TemplateParameters,
216                              SmallVectorImpl<unsigned> *Position);
217
218  StringRef correctTypoInTParamReference(
219                              StringRef Typo,
220                              const TemplateParameterList *TemplateParameters);
221
222  bool isBlockCommand(StringRef Name);
223  bool isParamCommand(StringRef Name);
224  bool isTParamCommand(StringRef Name);
225  bool isBriefCommand(StringRef Name);
226  bool isReturnsCommand(StringRef Name);
227  unsigned getBlockCommandNumArgs(StringRef Name);
228
229  bool isInlineCommand(StringRef Name) const;
230
231  InlineCommandComment::RenderKind
232  getInlineCommandRenderKind(StringRef Name) const;
233
234  bool isHTMLEndTagOptional(StringRef Name);
235  bool isHTMLEndTagForbidden(StringRef Name);
236};
237
238} // end namespace comments
239} // end namespace clang
240
241#endif
242
243