CommentSema.h revision 1ca7ecc8854ffea215c033a0d8482551bf1b73f0 
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  DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
60    return Diags.Report(Loc, DiagID);
61  }
62
63  /// A stack of HTML tags that are currently open (not matched with closing
64  /// tags).
65  SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
66
67public:
68  Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
69       DiagnosticsEngine &Diags);
70
71  void setDecl(const Decl *D);
72
73  /// Returns a copy of array, owned by Sema's allocator.
74  template<typename T>
75  ArrayRef<T> copyArray(ArrayRef<T> Source) {
76    size_t Size = Source.size();
77    if (Size != 0) {
78      T *Mem = Allocator.Allocate<T>(Size);
79      std::uninitialized_copy(Source.begin(), Source.end(), Mem);
80      return llvm::makeArrayRef(Mem, Size);
81    } else
82      return llvm::makeArrayRef(static_cast<T *>(NULL), 0);
83  }
84
85  ParagraphComment *actOnParagraphComment(
86      ArrayRef<InlineContentComment *> Content);
87
88  BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
89                                              SourceLocation LocEnd,
90                                              StringRef Name);
91
92  BlockCommandComment *actOnBlockCommandArgs(
93                              BlockCommandComment *Command,
94                              ArrayRef<BlockCommandComment::Argument> Args);
95
96  BlockCommandComment *actOnBlockCommandFinish(BlockCommandComment *Command,
97                                               ParagraphComment *Paragraph);
98
99  ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
100                                              SourceLocation LocEnd,
101                                              StringRef Name);
102
103  ParamCommandComment *actOnParamCommandDirectionArg(
104                                            ParamCommandComment *Command,
105                                            SourceLocation ArgLocBegin,
106                                            SourceLocation ArgLocEnd,
107                                            StringRef Arg);
108
109  ParamCommandComment *actOnParamCommandParamNameArg(
110                                            ParamCommandComment *Command,
111                                            SourceLocation ArgLocBegin,
112                                            SourceLocation ArgLocEnd,
113                                            StringRef Arg);
114
115  ParamCommandComment *actOnParamCommandFinish(ParamCommandComment *Command,
116                                               ParagraphComment *Paragraph);
117
118  TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
119                                                SourceLocation LocEnd,
120                                                StringRef Name);
121
122  TParamCommandComment *actOnTParamCommandParamNameArg(
123                                            TParamCommandComment *Command,
124                                            SourceLocation ArgLocBegin,
125                                            SourceLocation ArgLocEnd,
126                                            StringRef Arg);
127
128  TParamCommandComment *actOnTParamCommandFinish(TParamCommandComment *Command,
129                                                 ParagraphComment *Paragraph);
130
131  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
132                                           SourceLocation CommandLocEnd,
133                                           StringRef CommandName);
134
135  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
136                                           SourceLocation CommandLocEnd,
137                                           StringRef CommandName,
138                                           SourceLocation ArgLocBegin,
139                                           SourceLocation ArgLocEnd,
140                                           StringRef Arg);
141
142  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
143                                            SourceLocation LocEnd,
144                                            StringRef Name);
145
146  TextComment *actOnText(SourceLocation LocBegin,
147                         SourceLocation LocEnd,
148                         StringRef Text);
149
150  VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
151                                                StringRef Name);
152
153  VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
154                                                   StringRef Text);
155
156  VerbatimBlockComment *actOnVerbatimBlockFinish(
157                              VerbatimBlockComment *Block,
158                              SourceLocation CloseNameLocBegin,
159                              StringRef CloseName,
160                              ArrayRef<VerbatimBlockLineComment *> Lines);
161
162  VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
163                                         StringRef Name,
164                                         SourceLocation TextBegin,
165                                         StringRef Text);
166
167  HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
168                                              StringRef TagName);
169
170  HTMLStartTagComment *actOnHTMLStartTagFinish(
171                              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  bool isFunctionDecl();
185  bool isTemplateDecl();
186
187  ArrayRef<const ParmVarDecl *> getParamVars();
188
189  /// Extract all important semantic information from
190  /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
191  void inspectThisDecl();
192
193  /// Returns index of a function parameter with a given name.
194  unsigned resolveParmVarReference(StringRef Name,
195                                   ArrayRef<const ParmVarDecl *> ParamVars);
196
197  /// Returns index of a function parameter with the name closest to a given
198  /// typo.
199  unsigned correctTypoInParmVarReference(StringRef Typo,
200                                         ArrayRef<const ParmVarDecl *> ParamVars);
201
202  bool resolveTParamReference(StringRef Name,
203                              const TemplateParameterList *TemplateParameters,
204                              SmallVectorImpl<unsigned> *Position);
205
206  StringRef correctTypoInTParamReference(
207                              StringRef Typo,
208                              const TemplateParameterList *TemplateParameters);
209
210  bool isBlockCommand(StringRef Name);
211  bool isParamCommand(StringRef Name);
212  bool isTParamCommand(StringRef Name);
213  unsigned getBlockCommandNumArgs(StringRef Name);
214
215  bool isInlineCommand(StringRef Name) const;
216
217  InlineCommandComment::RenderKind
218  getInlineCommandRenderKind(StringRef Name) const;
219
220  bool isHTMLEndTagOptional(StringRef Name);
221  bool isHTMLEndTagForbidden(StringRef Name);
222};
223
224} // end namespace comments
225} // end namespace clang
226
227#endif
228
229