1 //===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 // This file defines the semantic analysis class for Doxygen comments.
11 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_CLANG_AST_COMMENTSEMA_H
14 #define LLVM_CLANG_AST_COMMENTSEMA_H
16 #include "clang/AST/Comment.h"
17 #include "clang/Basic/Diagnostic.h"
18 #include "clang/Basic/SourceLocation.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"
33 Sema(const Sema &) = delete;
34 void operator=(const Sema &) = delete;
36 /// Allocator for AST nodes.
37 llvm::BumpPtrAllocator &Allocator;
39 /// Source manager for the comment being parsed.
40 const SourceManager &SourceMgr;
42 DiagnosticsEngine &Diags;
44 CommandTraits &Traits;
46 const Preprocessor *PP;
48 /// Information about the declaration this comment is attached to.
49 DeclInfo *ThisDeclInfo;
51 /// Comment AST nodes that correspond to parameter names in
52 /// \c TemplateParameters.
54 /// Contains a valid value if \c DeclInfo->IsFilled is true.
55 llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
57 /// AST node for the \command and its aliases.
58 const BlockCommandComment *BriefCommand;
60 /// AST node for the \\headerfile command.
61 const BlockCommandComment *HeaderfileCommand;
63 DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
64 return Diags.Report(Loc, DiagID);
67 /// A stack of HTML tags that are currently open (not matched with closing
69 SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
72 Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
73 DiagnosticsEngine &Diags, CommandTraits &Traits,
74 const Preprocessor *PP);
76 void setDecl(const Decl *D);
78 /// Returns a copy of array, owned by Sema's allocator.
80 ArrayRef<T> copyArray(ArrayRef<T> Source) {
82 return Source.copy(Allocator);
86 ParagraphComment *actOnParagraphComment(
87 ArrayRef<InlineContentComment *> Content);
89 BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
90 SourceLocation LocEnd,
92 CommandMarkerKind CommandMarker);
94 void actOnBlockCommandArgs(BlockCommandComment *Command,
95 ArrayRef<BlockCommandComment::Argument> Args);
97 void actOnBlockCommandFinish(BlockCommandComment *Command,
98 ParagraphComment *Paragraph);
100 ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
101 SourceLocation LocEnd,
103 CommandMarkerKind CommandMarker);
105 void actOnParamCommandDirectionArg(ParamCommandComment *Command,
106 SourceLocation ArgLocBegin,
107 SourceLocation ArgLocEnd,
110 void actOnParamCommandParamNameArg(ParamCommandComment *Command,
111 SourceLocation ArgLocBegin,
112 SourceLocation ArgLocEnd,
115 void actOnParamCommandFinish(ParamCommandComment *Command,
116 ParagraphComment *Paragraph);
118 TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
119 SourceLocation LocEnd,
121 CommandMarkerKind CommandMarker);
123 void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
124 SourceLocation ArgLocBegin,
125 SourceLocation ArgLocEnd,
128 void actOnTParamCommandFinish(TParamCommandComment *Command,
129 ParagraphComment *Paragraph);
131 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
132 SourceLocation CommandLocEnd,
135 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
136 SourceLocation CommandLocEnd,
138 SourceLocation ArgLocBegin,
139 SourceLocation ArgLocEnd,
142 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
143 SourceLocation LocEnd,
144 StringRef CommandName);
146 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
147 SourceLocation LocEnd,
150 TextComment *actOnText(SourceLocation LocBegin,
151 SourceLocation LocEnd,
154 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
157 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
160 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
161 SourceLocation CloseNameLocBegin,
163 ArrayRef<VerbatimBlockLineComment *> Lines);
165 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
167 SourceLocation TextBegin,
170 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
173 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
174 ArrayRef<HTMLStartTagComment::Attribute> Attrs,
175 SourceLocation GreaterLoc,
178 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
179 SourceLocation LocEnd,
182 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
184 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
186 void checkReturnsCommand(const BlockCommandComment *Command);
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);
192 void checkDeprecatedCommand(const BlockCommandComment *Comment);
194 void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
196 void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
198 void checkContainerDecl(const BlockCommandComment *Comment);
200 /// Resolve parameter names to parameter indexes in function declaration.
201 /// Emit diagnostics about unknown parametrs.
202 void resolveParamCommandIndexes(const FullComment *FC);
204 bool isFunctionDecl();
205 bool isAnyFunctionDecl();
207 /// \returns \c true if declaration that this comment is attached to declares
208 /// a function pointer.
209 bool isFunctionPointerVarDecl();
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
213 bool isFunctionOrBlockPointerVarLikeDecl();
214 bool isFunctionOrMethodVariadic();
215 bool isObjCMethodDecl();
216 bool isObjCPropertyDecl();
217 bool isTemplateOrSpecialization();
218 bool isRecordLikeDecl();
219 bool isClassOrStructDecl();
221 bool isObjCInterfaceDecl();
222 bool isObjCProtocolDecl();
223 bool isClassTemplateDecl();
224 bool isFunctionTemplateDecl();
226 ArrayRef<const ParmVarDecl *> getParamVars();
228 /// Extract all important semantic information from
229 /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
230 void inspectThisDecl();
232 /// Returns index of a function parameter with a given name.
233 unsigned resolveParmVarReference(StringRef Name,
234 ArrayRef<const ParmVarDecl *> ParamVars);
236 /// Returns index of a function parameter with the name closest to a given
238 unsigned correctTypoInParmVarReference(StringRef Typo,
239 ArrayRef<const ParmVarDecl *> ParamVars);
241 bool resolveTParamReference(StringRef Name,
242 const TemplateParameterList *TemplateParameters,
243 SmallVectorImpl<unsigned> *Position);
245 StringRef correctTypoInTParamReference(
247 const TemplateParameterList *TemplateParameters);
249 InlineCommandComment::RenderKind
250 getInlineCommandRenderKind(StringRef Name) const;
253 } // end namespace comments
254 } // end namespace clang