clang  6.0.0svn
CommentSema.h
Go to the documentation of this file.
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"
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 
25 namespace clang {
26 class Decl;
27 class SourceMgr;
28 class Preprocessor;
29 
30 namespace comments {
31 class CommandTraits;
32 
33 class 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).
71 
72 public:
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>
82  if (!Source.empty())
83  return Source.copy(Allocator);
84  return None;
85  }
86 
89 
91  SourceLocation LocEnd,
92  unsigned CommandID,
93  CommandMarkerKind CommandMarker);
94 
97 
99  ParagraphComment *Paragraph);
100 
102  SourceLocation LocEnd,
103  unsigned CommandID,
104  CommandMarkerKind CommandMarker);
105 
107  SourceLocation ArgLocBegin,
108  SourceLocation ArgLocEnd,
109  StringRef Arg);
110 
112  SourceLocation ArgLocBegin,
113  SourceLocation ArgLocEnd,
114  StringRef Arg);
115 
117  ParagraphComment *Paragraph);
118 
120  SourceLocation LocEnd,
121  unsigned CommandID,
122  CommandMarkerKind CommandMarker);
123 
125  SourceLocation ArgLocBegin,
126  SourceLocation ArgLocEnd,
127  StringRef Arg);
128 
130  ParagraphComment *Paragraph);
131 
133  SourceLocation CommandLocEnd,
134  unsigned CommandID);
135 
137  SourceLocation CommandLocEnd,
138  unsigned CommandID,
139  SourceLocation ArgLocBegin,
140  SourceLocation ArgLocEnd,
141  StringRef Arg);
142 
144  SourceLocation LocEnd,
145  StringRef CommandName);
146 
148  SourceLocation LocEnd,
149  unsigned CommandID);
150 
152  SourceLocation LocEnd,
153  StringRef Text);
154 
156  unsigned CommandID);
157 
159  StringRef Text);
160 
162  SourceLocation CloseNameLocBegin,
163  StringRef CloseName,
165 
167  unsigned CommandID,
168  SourceLocation TextBegin,
169  StringRef Text);
170 
172  StringRef TagName);
173 
176  SourceLocation GreaterLoc,
177  bool IsSelfClosing);
178 
180  SourceLocation LocEnd,
181  StringRef TagName);
182 
184 
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 
194 
196 
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.
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.
216  bool isObjCMethodDecl();
217  bool isObjCPropertyDecl();
219  bool isRecordLikeDecl();
220  bool isClassOrStructDecl();
221  bool isUnionDecl();
222  bool isObjCInterfaceDecl();
223  bool isObjCProtocolDecl();
224  bool isClassTemplateDecl();
225  bool isFunctionTemplateDecl();
226 
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,
236 
237  /// Returns index of a function parameter with the name closest to a given
238  /// typo.
239  unsigned correctTypoInParmVarReference(StringRef Typo,
241 
242  bool resolveTParamReference(StringRef Name,
243  const TemplateParameterList *TemplateParameters,
244  SmallVectorImpl<unsigned> *Position);
245 
247  StringRef Typo,
248  const TemplateParameterList *TemplateParameters);
249 
251  getInlineCommandRenderKind(StringRef Name) const;
252 };
253 
254 } // end namespace comments
255 } // end namespace clang
256 
257 #endif
258 
void actOnParamCommandFinish(ParamCommandComment *Command, ParagraphComment *Paragraph)
StringRef correctTypoInTParamReference(StringRef Typo, const TemplateParameterList *TemplateParameters)
ArrayRef< const ParmVarDecl * > getParamVars()
void checkBlockCommandEmptyParagraph(BlockCommandComment *Command)
void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag, ArrayRef< HTMLStartTagComment::Attribute > Attrs, SourceLocation GreaterLoc, bool IsSelfClosing)
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:86
ParagraphComment * actOnParagraphComment(ArrayRef< InlineContentComment *> Content)
Definition: CommentSema.cpp:45
VerbatimBlockComment * actOnVerbatimBlockStart(SourceLocation Loc, unsigned CommandID)
DiagnosticBuilder Report(SourceLocation Loc, unsigned DiagID)
Issue the message to the client.
Definition: Diagnostic.h:1207
The l-value was an access to a declared entity or something equivalently strong, like the address of ...
unsigned correctTypoInParmVarReference(StringRef Typo, ArrayRef< const ParmVarDecl *> ParamVars)
Returns index of a function parameter with the name closest to a given typo.
HTMLStartTagComment * actOnHTMLStartTagStart(SourceLocation LocBegin, StringRef TagName)
void actOnBlockCommandArgs(BlockCommandComment *Command, ArrayRef< BlockCommandComment::Argument > Args)
Definition: CommentSema.cpp:62
void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment)
Stores a list of template parameters for a TemplateDecl and its derived classes.
Definition: DeclTemplate.h:68
void checkBlockCommandDuplicate(const BlockCommandComment *Command)
Emit diagnostics about duplicate block commands that should be used only once per comment...
void actOnVerbatimBlockFinish(VerbatimBlockComment *Block, SourceLocation CloseNameLocBegin, StringRef CloseName, ArrayRef< VerbatimBlockLineComment *> Lines)
TextComment * actOnText(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text)
A command with word-like arguments that is considered inline content.
Definition: Comment.h:303
A line of text contained in a verbatim block.
Definition: Comment.h:869
A verbatim line command.
Definition: Comment.h:949
void checkReturnsCommand(const BlockCommandComment *Command)
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:147
InlineContentComment * actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, StringRef CommandName)
FullComment * actOnFullComment(ArrayRef< BlockContentComment *> Blocks)
Any part of the comment.
Definition: Comment.h:53
Defines the Diagnostic-related interfaces.
Inline content (contained within a block).
Definition: Comment.h:242
RenderKind
The most appropriate rendering mode for this command, chosen on command semantics in Doxygen...
Definition: Comment.h:314
ArrayRef< T > copyArray(ArrayRef< T > Source)
Returns a copy of array, owned by Sema&#39;s allocator.
Definition: CommentSema.h:81
A verbatim block command (e.
Definition: Comment.h:897
A little helper class used to produce diagnostics.
Definition: Diagnostic.h:955
bool resolveTParamReference(StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl< unsigned > *Position)
void inspectThisDecl()
Extract all important semantic information from ThisDeclInfo->ThisDecl into ThisDeclInfo members...
void actOnTParamCommandFinish(TParamCommandComment *Command, ParagraphComment *Paragraph)
CommandMarkerKind
Describes the syntax that was used in a documentation command.
Definition: Comment.h:37
A command that has zero or more word-like arguments (number of word-like arguments depends on command...
Definition: Comment.h:602
VerbatimBlockLineComment * actOnVerbatimBlockLine(SourceLocation Loc, StringRef Text)
unsigned resolveParmVarReference(StringRef Name, ArrayRef< const ParmVarDecl *> ParamVars)
Returns index of a function parameter with a given name.
An opening HTML tag with attributes.
Definition: Comment.h:419
void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:98
TParamCommandComment * actOnTParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
void actOnBlockCommandFinish(BlockCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:67
This class provides information about commands that can be used in comments.
InlineCommandComment::RenderKind getInlineCommandRenderKind(StringRef Name) const
void checkDeprecatedCommand(const BlockCommandComment *Comment)
void checkContainerDecl(const BlockCommandComment *Comment)
Encodes a location in the source.
VerbatimLineComment * actOnVerbatimLine(SourceLocation LocBegin, unsigned CommandID, SourceLocation TextBegin, StringRef Text)
bool isFunctionOrBlockPointerVarLikeDecl()
ParamCommandComment * actOnParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:80
A closing HTML tag.
Definition: Comment.h:513
Doxygen \tparam command, describes a template parameter.
Definition: Comment.h:805
Dataflow Directional Tag Classes.
BlockCommandComment * actOnBlockCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:50
Information about the declaration, useful to clients of FullComment.
Definition: Comment.h:986
A single paragraph that contains inline content.
Definition: Comment.h:552
HTMLEndTagComment * actOnHTMLEndTag(SourceLocation LocBegin, SourceLocation LocEnd, StringRef TagName)
void actOnTParamCommandParamNameArg(TParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Defines the clang::SourceLocation class and associated facilities.
void setDecl(const Decl *D)
Definition: CommentSema.cpp:36
InlineCommandComment * actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID)
Doxygen \param command.
Definition: Comment.h:717
StringRef Text
Definition: Format.cpp:1346
void actOnParamCommandParamNameArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
void resolveParamCommandIndexes(const FullComment *FC)
Resolve parameter names to parameter indexes in function declaration.
This class handles loading and caching of source files into memory.
void actOnParamCommandDirectionArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
A full comment attached to a declaration, contains block content.
Definition: Comment.h:1097
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:127