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_COMMENTSEMA_H
15#define LLVM_CLANG_AST_COMMENTSEMA_H
16
17#include "clang/AST/Comment.h"
18#include "clang/Basic/Diagnostic.h"
19#include "clang/Basic/SourceLocation.h"
20#include "llvm/ADT/ArrayRef.h"
21#include "llvm/ADT/StringMap.h"
22#include "llvm/ADT/StringRef.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 &) = delete;
35  void operator=(const Sema &) = delete;
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 \\headerfile command.
62  const BlockCommandComment *HeaderfileCommand;
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    if (!Source.empty())
83      return Source.copy(Allocator);
84    return None;
85  }
86
87  ParagraphComment *actOnParagraphComment(
88      ArrayRef<InlineContentComment *> Content);
89
90  BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
91                                              SourceLocation LocEnd,
92                                              unsigned CommandID,
93                                              CommandMarkerKind CommandMarker);
94
95  void actOnBlockCommandArgs(BlockCommandComment *Command,
96                             ArrayRef<BlockCommandComment::Argument> Args);
97
98  void actOnBlockCommandFinish(BlockCommandComment *Command,
99                               ParagraphComment *Paragraph);
100
101  ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
102                                              SourceLocation LocEnd,
103                                              unsigned CommandID,
104                                              CommandMarkerKind CommandMarker);
105
106  void actOnParamCommandDirectionArg(ParamCommandComment *Command,
107                                     SourceLocation ArgLocBegin,
108                                     SourceLocation ArgLocEnd,
109                                     StringRef Arg);
110
111  void actOnParamCommandParamNameArg(ParamCommandComment *Command,
112                                     SourceLocation ArgLocBegin,
113                                     SourceLocation ArgLocEnd,
114                                     StringRef Arg);
115
116  void actOnParamCommandFinish(ParamCommandComment *Command,
117                               ParagraphComment *Paragraph);
118
119  TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
120                                                SourceLocation LocEnd,
121                                                unsigned CommandID,
122                                                CommandMarkerKind CommandMarker);
123
124  void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
125                                      SourceLocation ArgLocBegin,
126                                      SourceLocation ArgLocEnd,
127                                      StringRef Arg);
128
129  void actOnTParamCommandFinish(TParamCommandComment *Command,
130                                ParagraphComment *Paragraph);
131
132  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
133                                           SourceLocation CommandLocEnd,
134                                           unsigned CommandID);
135
136  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
137                                           SourceLocation CommandLocEnd,
138                                           unsigned CommandID,
139                                           SourceLocation ArgLocBegin,
140                                           SourceLocation ArgLocEnd,
141                                           StringRef Arg);
142
143  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
144                                            SourceLocation LocEnd,
145                                            StringRef CommandName);
146
147  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
148                                            SourceLocation LocEnd,
149                                            unsigned CommandID);
150
151  TextComment *actOnText(SourceLocation LocBegin,
152                         SourceLocation LocEnd,
153                         StringRef Text);
154
155  VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
156                                                unsigned CommandID);
157
158  VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
159                                                   StringRef Text);
160
161  void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
162                                SourceLocation CloseNameLocBegin,
163                                StringRef CloseName,
164                                ArrayRef<VerbatimBlockLineComment *> Lines);
165
166  VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
167                                         unsigned CommandID,
168                                         SourceLocation TextBegin,
169                                         StringRef Text);
170
171  HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
172                                              StringRef TagName);
173
174  void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
175                               ArrayRef<HTMLStartTagComment::Attribute> Attrs,
176                               SourceLocation GreaterLoc,
177                               bool IsSelfClosing);
178
179  HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
180                                     SourceLocation LocEnd,
181                                     StringRef TagName);
182
183  FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
184
185  void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
186
187  void checkReturnsCommand(const BlockCommandComment *Command);
188
189  /// Emit diagnostics about duplicate block commands that should be
190  /// used only once per comment, e.g., \\brief and \\returns.
191  void checkBlockCommandDuplicate(const BlockCommandComment *Command);
192
193  void checkDeprecatedCommand(const BlockCommandComment *Comment);
194
195  void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
196
197  void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
198
199  void checkContainerDecl(const BlockCommandComment *Comment);
200
201  /// Resolve parameter names to parameter indexes in function declaration.
202  /// Emit diagnostics about unknown parametrs.
203  void resolveParamCommandIndexes(const FullComment *FC);
204
205  bool isFunctionDecl();
206  bool isAnyFunctionDecl();
207
208  /// \returns \c true if declaration that this comment is attached to declares
209  /// a function pointer.
210  bool isFunctionPointerVarDecl();
211  /// \returns \c true if the declaration that this comment is attached to
212  /// declares a variable or a field whose type is a function or a block
213  /// pointer.
214  bool isFunctionOrBlockPointerVarLikeDecl();
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