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 |
15 | |
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" |
23 | |
24 | namespace clang { |
25 | class Decl; |
26 | class SourceMgr; |
27 | class Preprocessor; |
28 | |
29 | namespace comments { |
30 | class CommandTraits; |
31 | |
32 | class { |
33 | (const Sema &) = delete; |
34 | void (const Sema &) = delete; |
35 | |
36 | /// Allocator for AST nodes. |
37 | llvm::BumpPtrAllocator &; |
38 | |
39 | /// Source manager for the comment being parsed. |
40 | const SourceManager &; |
41 | |
42 | DiagnosticsEngine &; |
43 | |
44 | CommandTraits &; |
45 | |
46 | const Preprocessor *; |
47 | |
48 | /// Information about the declaration this comment is attached to. |
49 | DeclInfo *; |
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 *> ; |
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 (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). |
69 | SmallVector<HTMLStartTagComment *, 8> ; |
70 | |
71 | public: |
72 | (llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr, |
73 | DiagnosticsEngine &Diags, CommandTraits &Traits, |
74 | const Preprocessor *PP); |
75 | |
76 | void (const Decl *D); |
77 | |
78 | /// Returns a copy of array, owned by Sema's allocator. |
79 | template<typename T> |
80 | ArrayRef<T> (ArrayRef<T> Source) { |
81 | if (!Source.empty()) |
82 | return Source.copy(Allocator); |
83 | return std::nullopt; |
84 | } |
85 | |
86 | ParagraphComment *( |
87 | ArrayRef<InlineContentComment *> Content); |
88 | |
89 | BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin, |
90 | SourceLocation LocEnd, |
91 | unsigned CommandID, |
92 | CommandMarkerKind CommandMarker); |
93 | |
94 | void actOnBlockCommandArgs(BlockCommandComment *Command, |
95 | ArrayRef<BlockCommandComment::Argument> Args); |
96 | |
97 | void actOnBlockCommandFinish(BlockCommandComment *Command, |
98 | ParagraphComment *Paragraph); |
99 | |
100 | ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin, |
101 | SourceLocation LocEnd, |
102 | unsigned CommandID, |
103 | CommandMarkerKind CommandMarker); |
104 | |
105 | void actOnParamCommandDirectionArg(ParamCommandComment *Command, |
106 | SourceLocation ArgLocBegin, |
107 | SourceLocation ArgLocEnd, |
108 | StringRef Arg); |
109 | |
110 | void actOnParamCommandParamNameArg(ParamCommandComment *Command, |
111 | SourceLocation ArgLocBegin, |
112 | SourceLocation ArgLocEnd, |
113 | StringRef Arg); |
114 | |
115 | void actOnParamCommandFinish(ParamCommandComment *Command, |
116 | ParagraphComment *Paragraph); |
117 | |
118 | TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin, |
119 | SourceLocation LocEnd, |
120 | unsigned CommandID, |
121 | CommandMarkerKind CommandMarker); |
122 | |
123 | void actOnTParamCommandParamNameArg(TParamCommandComment *Command, |
124 | SourceLocation ArgLocBegin, |
125 | SourceLocation ArgLocEnd, |
126 | StringRef Arg); |
127 | |
128 | void actOnTParamCommandFinish(TParamCommandComment *Command, |
129 | ParagraphComment *Paragraph); |
130 | |
131 | InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin, |
132 | SourceLocation CommandLocEnd, |
133 | unsigned CommandID, |
134 | ArrayRef<Comment::Argument> Args); |
135 | |
136 | InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin, |
137 | SourceLocation LocEnd, |
138 | StringRef CommandName); |
139 | |
140 | InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin, |
141 | SourceLocation LocEnd, |
142 | unsigned CommandID); |
143 | |
144 | TextComment *(SourceLocation LocBegin, |
145 | SourceLocation LocEnd, |
146 | StringRef Text); |
147 | |
148 | VerbatimBlockComment *(SourceLocation Loc, |
149 | unsigned CommandID); |
150 | |
151 | VerbatimBlockLineComment *(SourceLocation Loc, |
152 | StringRef Text); |
153 | |
154 | void (VerbatimBlockComment *Block, |
155 | SourceLocation CloseNameLocBegin, |
156 | StringRef CloseName, |
157 | ArrayRef<VerbatimBlockLineComment *> Lines); |
158 | |
159 | VerbatimLineComment *(SourceLocation LocBegin, |
160 | unsigned CommandID, |
161 | SourceLocation TextBegin, |
162 | StringRef Text); |
163 | |
164 | HTMLStartTagComment *(SourceLocation LocBegin, |
165 | StringRef TagName); |
166 | |
167 | void (HTMLStartTagComment *Tag, |
168 | ArrayRef<HTMLStartTagComment::Attribute> Attrs, |
169 | SourceLocation GreaterLoc, |
170 | bool IsSelfClosing); |
171 | |
172 | HTMLEndTagComment *(SourceLocation LocBegin, |
173 | SourceLocation LocEnd, |
174 | StringRef TagName); |
175 | |
176 | FullComment *(ArrayRef<BlockContentComment *> Blocks); |
177 | |
178 | private: |
179 | void checkBlockCommandEmptyParagraph(BlockCommandComment *Command); |
180 | |
181 | void checkReturnsCommand(const BlockCommandComment *Command); |
182 | |
183 | /// Emit diagnostics about duplicate block commands that should be |
184 | /// used only once per comment, e.g., \and \\returns. |
185 | void checkBlockCommandDuplicate(const BlockCommandComment *Command); |
186 | |
187 | void checkDeprecatedCommand(const BlockCommandComment *); |
188 | |
189 | void checkFunctionDeclVerbatimLine(const BlockCommandComment *); |
190 | |
191 | void checkContainerDeclVerbatimLine(const BlockCommandComment *); |
192 | |
193 | void checkContainerDecl(const BlockCommandComment *); |
194 | |
195 | /// Resolve parameter names to parameter indexes in function declaration. |
196 | /// Emit diagnostics about unknown parameters. |
197 | void resolveParamCommandIndexes(const FullComment *FC); |
198 | |
199 | /// \returns \c true if the declaration that this comment is attached to |
200 | /// is a pointer to function/method/block type or has such a type. |
201 | bool (); |
202 | |
203 | bool (); |
204 | bool (); |
205 | |
206 | /// \returns \c true if declaration that this comment is attached to declares |
207 | /// a function pointer. |
208 | bool (); |
209 | bool (); |
210 | bool (); |
211 | bool (); |
212 | bool (); |
213 | bool (); |
214 | bool (); |
215 | /// \return \c true if the declaration that this comment is attached to |
216 | /// declares either struct, class or tag typedef. |
217 | bool (); |
218 | bool (); |
219 | bool (); |
220 | bool (); |
221 | bool (); |
222 | bool (); |
223 | |
224 | ArrayRef<const ParmVarDecl *> (); |
225 | |
226 | /// Extract all important semantic information from |
227 | /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members. |
228 | void (); |
229 | |
230 | /// Returns index of a function parameter with a given name. |
231 | unsigned (StringRef Name, |
232 | ArrayRef<const ParmVarDecl *> ParamVars); |
233 | |
234 | /// Returns index of a function parameter with the name closest to a given |
235 | /// typo. |
236 | unsigned (StringRef Typo, |
237 | ArrayRef<const ParmVarDecl *> ParamVars); |
238 | |
239 | bool (StringRef Name, |
240 | const TemplateParameterList *TemplateParameters, |
241 | SmallVectorImpl<unsigned> *Position); |
242 | |
243 | StringRef ( |
244 | StringRef Typo, |
245 | const TemplateParameterList *TemplateParameters); |
246 | |
247 | InlineCommandRenderKind getInlineCommandRenderKind(StringRef Name) const; |
248 | }; |
249 | |
250 | } // end namespace comments |
251 | } // end namespace clang |
252 | |
253 | #endif |
254 | |
255 | |