clang  14.0.0git
CommentSema.h
Go to the documentation of this file.
1 //===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This file defines the semantic analysis class for Doxygen comments.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_CLANG_AST_COMMENTSEMA_H
14 #define LLVM_CLANG_AST_COMMENTSEMA_H
15 
16 #include "clang/AST/Comment.h"
17 #include "clang/Basic/Diagnostic.h"
19 #include "llvm/ADT/ArrayRef.h"
20 #include "llvm/ADT/StringMap.h"
21 #include "llvm/ADT/StringRef.h"
22 #include "llvm/Support/Allocator.h"
23 
24 namespace clang {
25 class Decl;
26 class SourceMgr;
27 class Preprocessor;
28 
29 namespace comments {
30 class CommandTraits;
31 
32 class Sema {
33  Sema(const Sema &) = delete;
34  void operator=(const Sema &) = delete;
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  const Preprocessor *PP;
47 
48  /// Information about the declaration this comment is attached to.
49  DeclInfo *ThisDeclInfo;
50 
51  /// Comment AST nodes that correspond to parameter names in
52  /// \c TemplateParameters.
53  ///
54  /// Contains a valid value if \c DeclInfo->IsFilled is true.
55  llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
56 
57  /// AST node for the \command and its aliases.
58  const BlockCommandComment *BriefCommand;
59 
60  /// AST node for the \\headerfile command.
61  const BlockCommandComment *HeaderfileCommand;
62 
63  DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
64  return Diags.Report(Loc, DiagID);
65  }
66 
67  /// A stack of HTML tags that are currently open (not matched with closing
68  /// tags).
70 
71 public:
72  Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
73  DiagnosticsEngine &Diags, CommandTraits &Traits,
74  const Preprocessor *PP);
75 
76  void setDecl(const Decl *D);
77 
78  /// Returns a copy of array, owned by Sema's allocator.
79  template<typename T>
81  if (!Source.empty())
82  return Source.copy(Allocator);
83  return None;
84  }
85 
88 
90  SourceLocation LocEnd,
91  unsigned CommandID,
92  CommandMarkerKind CommandMarker);
93 
96 
98  ParagraphComment *Paragraph);
99 
101  SourceLocation LocEnd,
102  unsigned CommandID,
103  CommandMarkerKind CommandMarker);
104 
106  SourceLocation ArgLocBegin,
107  SourceLocation ArgLocEnd,
108  StringRef Arg);
109 
111  SourceLocation ArgLocBegin,
112  SourceLocation ArgLocEnd,
113  StringRef Arg);
114 
116  ParagraphComment *Paragraph);
117 
119  SourceLocation LocEnd,
120  unsigned CommandID,
121  CommandMarkerKind CommandMarker);
122 
124  SourceLocation ArgLocBegin,
125  SourceLocation ArgLocEnd,
126  StringRef Arg);
127 
129  ParagraphComment *Paragraph);
130 
132  SourceLocation CommandLocEnd,
133  unsigned CommandID);
134 
136  SourceLocation CommandLocEnd,
137  unsigned CommandID,
138  SourceLocation ArgLocBegin,
139  SourceLocation ArgLocEnd,
140  StringRef Arg);
141 
143  SourceLocation LocEnd,
144  StringRef CommandName);
145 
147  SourceLocation LocEnd,
148  unsigned CommandID);
149 
151  SourceLocation LocEnd,
152  StringRef Text);
153 
155  unsigned CommandID);
156 
158  StringRef Text);
159 
161  SourceLocation CloseNameLocBegin,
162  StringRef CloseName,
164 
166  unsigned CommandID,
167  SourceLocation TextBegin,
168  StringRef Text);
169 
171  StringRef TagName);
172 
175  SourceLocation GreaterLoc,
176  bool IsSelfClosing);
177 
179  SourceLocation LocEnd,
180  StringRef TagName);
181 
183 
185 
186  void checkReturnsCommand(const BlockCommandComment *Command);
187 
188  /// Emit diagnostics about duplicate block commands that should be
189  /// used only once per comment, e.g., \and \\returns.
190  void checkBlockCommandDuplicate(const BlockCommandComment *Command);
191 
193 
195 
197 
199 
200  /// Resolve parameter names to parameter indexes in function declaration.
201  /// Emit diagnostics about unknown parametrs.
202  void resolveParamCommandIndexes(const FullComment *FC);
203 
204  bool isFunctionDecl();
205  bool isAnyFunctionDecl();
206 
207  /// \returns \c true if declaration that this comment is attached to declares
208  /// a function pointer.
210  /// \returns \c true if the declaration that this comment is attached to
211  /// declares a variable or a field whose type is a function or a block
212  /// pointer.
215  bool isObjCMethodDecl();
216  bool isObjCPropertyDecl();
218  bool isRecordLikeDecl();
219  bool isClassOrStructDecl();
220  /// \return \c true if the declaration that this comment is attached to
221  /// declares either struct, class or tag typedef.
223  bool isUnionDecl();
224  bool isObjCInterfaceDecl();
225  bool isObjCProtocolDecl();
226  bool isClassTemplateDecl();
227  bool isFunctionTemplateDecl();
228 
230 
231  /// Extract all important semantic information from
232  /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
233  void inspectThisDecl();
234 
235  /// Returns index of a function parameter with a given name.
236  unsigned resolveParmVarReference(StringRef Name,
238 
239  /// Returns index of a function parameter with the name closest to a given
240  /// typo.
241  unsigned correctTypoInParmVarReference(StringRef Typo,
243 
244  bool resolveTParamReference(StringRef Name,
245  const TemplateParameterList *TemplateParameters,
246  SmallVectorImpl<unsigned> *Position);
247 
249  StringRef Typo,
250  const TemplateParameterList *TemplateParameters);
251 
253  getInlineCommandRenderKind(StringRef Name) const;
254 };
255 
256 } // end namespace comments
257 } // end namespace clang
258 
259 #endif
260 
clang::comments::Sema::checkContainerDecl
void checkContainerDecl(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:170
clang::comments::Sema::actOnVerbatimLine
VerbatimLineComment * actOnVerbatimLine(SourceLocation LocBegin, unsigned CommandID, SourceLocation TextBegin, StringRef Text)
Definition: CommentSema.cpp:445
clang::comments::VerbatimLineComment
A verbatim line command.
Definition: Comment.h:943
clang::comments::Sema::isFunctionOrBlockPointerVarLikeDecl
bool isFunctionOrBlockPointerVarLikeDecl()
Definition: CommentSema.cpp:876
clang::comments::Sema::actOnParamCommandStart
ParamCommandComment * actOnParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:80
clang::comments::Sema::inspectThisDecl
void inspectThisDecl()
Extract all important semantic information from ThisDeclInfo->ThisDecl into ThisDeclInfo members.
Definition: CommentSema.cpp:1029
clang::comments::Sema::actOnTParamCommandFinish
void actOnTParamCommandFinish(TParamCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:360
clang::DiagnosticBuilder
A little helper class used to produce diagnostics.
Definition: Diagnostic.h:1264
clang::comments::Sema
Definition: CommentSema.h:32
llvm::SmallVector
Definition: LLVM.h:38
clang::SourceLocation
Encodes a location in the source.
Definition: SourceLocation.h:88
clang::DiagnosticsEngine
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:191
clang::comments::Sema::getInlineCommandRenderKind
InlineCommandComment::RenderKind getInlineCommandRenderKind(StringRef Name) const
Definition: CommentSema.cpp:1177
clang::comments::Sema::actOnParagraphComment
ParagraphComment * actOnParagraphComment(ArrayRef< InlineContentComment * > Content)
Definition: CommentSema.cpp:45
clang::comments::Sema::checkDeprecatedCommand
void checkDeprecatedCommand(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:667
clang::comments::Sema::isAnyFunctionDecl
bool isAnyFunctionDecl()
Definition: CommentSema.cpp:829
clang::comments::Sema::isObjCProtocolDecl
bool isObjCProtocolDecl()
Definition: CommentSema.cpp:1014
clang::comments::HTMLEndTagComment
A closing HTML tag.
Definition: Comment.h:507
clang::comments::InlineContentComment
Inline content (contained within a block).
Definition: Comment.h:236
clang::comments::Sema::isClassOrStructOrTagTypedefDecl
bool isClassOrStructOrTagTypedefDecl()
Definition: CommentSema.cpp:960
clang::comments::Sema::isUnionDecl
bool isUnionDecl()
Definition: CommentSema.cpp:931
clang::comments::Sema::actOnTParamCommandParamNameArg
void actOnTParamCommandParamNameArg(TParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:301
clang::comments::Sema::actOnFullComment
FullComment * actOnFullComment(ArrayRef< BlockContentComment * > Blocks)
Definition: CommentSema.cpp:546
clang::SourceManager
This class handles loading and caching of source files into memory.
Definition: SourceManager.h:626
clang::comments::Sema::setDecl
void setDecl(const Decl *D)
Definition: CommentSema.cpp:36
clang::comments::InlineCommandComment
A command with word-like arguments that is considered inline content.
Definition: Comment.h:297
clang::CodeGen::AlignmentSource::Decl
@ Decl
The l-value was an access to a declared entity or something equivalently strong, like the address of ...
clang::comments::VerbatimBlockLineComment
A line of text contained in a verbatim block.
Definition: Comment.h:863
clang::comments::ParamCommandComment
Doxygen \param command.
Definition: Comment.h:711
clang::comments::Comment
Any part of the comment.
Definition: Comment.h:52
clang::comments::Sema::actOnBlockCommandStart
BlockCommandComment * actOnBlockCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:50
clang::comments::Sema::isRecordLikeDecl
bool isRecordLikeDecl()
Definition: CommentSema.cpp:922
clang::comments::Sema::actOnInlineCommand
InlineCommandComment * actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID)
Definition: CommentSema.cpp:366
clang::comments::Sema::actOnParamCommandParamNameArg
void actOnParamCommandParamNameArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:259
clang::comments::Sema::actOnHTMLEndTag
HTMLEndTagComment * actOnHTMLEndTag(SourceLocation LocBegin, SourceLocation LocEnd, StringRef TagName)
Definition: CommentSema.cpp:478
clang::comments::Sema::resolveParmVarReference
unsigned resolveParmVarReference(StringRef Name, ArrayRef< const ParmVarDecl * > ParamVars)
Returns index of a function parameter with a given name.
Definition: CommentSema.cpp:1033
clang::comments::Sema::resolveParamCommandIndexes
void resolveParamCommandIndexes(const FullComment *FC)
Resolve parameter names to parameter indexes in function declaration.
Definition: CommentSema.cpp:732
Diagnostic.h
clang::comments::Sema::actOnParamCommandFinish
void actOnParamCommandFinish(ParamCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:277
clang::comments::Sema::correctTypoInTParamReference
StringRef correctTypoInTParamReference(StringRef Typo, const TemplateParameterList *TemplateParameters)
Definition: CommentSema.cpp:1163
clang::comments::Sema::actOnVerbatimBlockFinish
void actOnVerbatimBlockFinish(VerbatimBlockComment *Block, SourceLocation CloseNameLocBegin, StringRef CloseName, ArrayRef< VerbatimBlockLineComment * > Lines)
Definition: CommentSema.cpp:436
clang::comments::FullComment
A full comment attached to a declaration, contains block content.
Definition: Comment.h:1091
clang::comments::Sema::isObjCInterfaceDecl
bool isObjCInterfaceDecl()
Definition: CommentSema.cpp:1005
clang::comments::CommandMarkerKind
CommandMarkerKind
Describes the syntax that was used in a documentation command.
Definition: Comment.h:36
clang::comments::Sema::isFunctionTemplateDecl
bool isFunctionTemplateDecl()
Definition: CommentSema.cpp:996
clang::comments::BlockCommandComment
A command that has zero or more word-like arguments (number of word-like arguments depends on command...
Definition: Comment.h:596
clang::TemplateParameterList
Stores a list of template parameters for a TemplateDecl and its derived classes.
Definition: DeclTemplate.h:69
clang::comments::Sema::actOnHTMLStartTagFinish
void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag, ArrayRef< HTMLStartTagComment::Attribute > Attrs, SourceLocation GreaterLoc, bool IsSelfClosing)
Definition: CommentSema.cpp:465
clang::comments::Sema::actOnVerbatimBlockStart
VerbatimBlockComment * actOnVerbatimBlockStart(SourceLocation Loc, unsigned CommandID)
Definition: CommentSema.cpp:422
clang::comments::Sema::correctTypoInParmVarReference
unsigned correctTypoInParmVarReference(StringRef Typo, ArrayRef< const ParmVarDecl * > ParamVars)
Returns index of a function parameter with the name closest to a given typo.
Definition: CommentSema.cpp:1098
clang::comments::HTMLStartTagComment
An opening HTML tag with attributes.
Definition: Comment.h:413
clang::comments::Sema::actOnParamCommandDirectionArg
void actOnParamCommandDirectionArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:230
SourceLocation.h
clang::comments::Sema::getParamVars
ArrayRef< const ParmVarDecl * > getParamVars()
Definition: CommentSema.cpp:1023
clang::comments::DeclInfo
Information about the declaration, useful to clients of FullComment.
Definition: Comment.h:980
clang::comments::Sema::isClassTemplateDecl
bool isClassTemplateDecl()
Definition: CommentSema.cpp:987
clang::comments::Sema::checkBlockCommandEmptyParagraph
void checkBlockCommandEmptyParagraph(BlockCommandComment *Command)
Definition: CommentSema.cpp:565
clang::comments::TParamCommandComment
Doxygen \tparam command, describes a template parameter.
Definition: Comment.h:799
llvm::ArrayRef
Definition: LLVM.h:34
clang::Decl
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:89
clang::comments::Sema::isFunctionOrMethodVariadic
bool isFunctionOrMethodVariadic()
Definition: CommentSema.cpp:834
clang::comments::Sema::actOnText
TextComment * actOnText(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text)
Definition: CommentSema.cpp:416
clang::comments::Sema::isClassOrStructDecl
bool isClassOrStructDecl()
Definition: CommentSema.cpp:948
clang::comments::Sema::checkReturnsCommand
void checkReturnsCommand(const BlockCommandComment *Command)
Definition: CommentSema.cpp:583
clang::comments::Sema::isFunctionPointerVarDecl
bool isFunctionPointerVarDecl()
Definition: CommentSema.cpp:862
clang::comments::Sema::actOnHTMLStartTagStart
HTMLStartTagComment * actOnHTMLStartTagStart(SourceLocation LocBegin, StringRef TagName)
Definition: CommentSema.cpp:460
clang::comments::Sema::actOnBlockCommandArgs
void actOnBlockCommandArgs(BlockCommandComment *Command, ArrayRef< BlockCommandComment::Argument > Args)
Definition: CommentSema.cpp:62
clang::comments::TextComment
Plain text.
Definition: Comment.h:261
clang::comments::Sema::checkContainerDeclVerbatimLine
void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:131
clang::comments::InlineCommandComment::RenderKind
RenderKind
The most appropriate rendering mode for this command, chosen on command semantics in Doxygen.
Definition: Comment.h:308
clang
Definition: CalledOnceCheck.h:17
clang::comments::Sema::checkBlockCommandDuplicate
void checkBlockCommandDuplicate(const BlockCommandComment *Command)
Emit diagnostics about duplicate block commands that should be used only once per comment,...
Definition: CommentSema.cpp:629
Text
StringRef Text
Definition: Format.cpp:2334
clang::comments::VerbatimBlockComment
A verbatim block command (e.
Definition: Comment.h:891
clang::comments::Sema::isTemplateOrSpecialization
bool isTemplateOrSpecialization()
Definition: CommentSema.cpp:914
clang::comments::Sema::resolveTParamReference
bool resolveTParamReference(StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl< unsigned > *Position)
Definition: CommentSema.cpp:1136
Comment.h
clang::comments::Sema::isObjCMethodDecl
bool isObjCMethodDecl()
Definition: CommentSema.cpp:857
llvm::SmallVectorImpl
Definition: LLVM.h:39
clang::comments::CommandTraits
This class provides information about commands that can be used in comments.
Definition: CommentCommandTraits.h:127
clang::Preprocessor
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:130
clang::comments::Sema::actOnVerbatimBlockLine
VerbatimBlockLineComment * actOnVerbatimBlockLine(SourceLocation Loc, StringRef Text)
Definition: CommentSema.cpp:431
clang::comments::Sema::actOnUnknownCommand
InlineContentComment * actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, StringRef CommandName)
Definition: CommentSema.cpp:399
clang::comments::Sema::checkFunctionDeclVerbatimLine
void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:98
clang::comments::Sema::isObjCPropertyDecl
bool isObjCPropertyDecl()
Definition: CommentSema.cpp:906
clang::comments::Sema::copyArray
ArrayRef< T > copyArray(ArrayRef< T > Source)
Returns a copy of array, owned by Sema's allocator.
Definition: CommentSema.h:80
clang::comments::Sema::actOnTParamCommandStart
TParamCommandComment * actOnTParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:283
clang::comments::Sema::actOnBlockCommandFinish
void actOnBlockCommandFinish(BlockCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:67
clang::comments::Sema::isFunctionDecl
bool isFunctionDecl()
Definition: CommentSema.cpp:821
clang::DiagnosticsEngine::Report
DiagnosticBuilder Report(SourceLocation Loc, unsigned DiagID)
Issue the message to the client.
Definition: Diagnostic.h:1523
clang::comments::ParagraphComment
A single paragraph that contains inline content.
Definition: Comment.h:546