xref: /freebsd/contrib/llvm-project/clang/include/clang/AST/CommentSema.h (revision 2f513db72b034fd5ef7f080b11be5c711c15186a)
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"
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 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).
69   SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
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>
80   ArrayRef<T> copyArray(ArrayRef<T> Source) {
81     if (!Source.empty())
82       return Source.copy(Allocator);
83     return None;
84   }
85 
86   ParagraphComment *actOnParagraphComment(
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 
135   InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
136                                            SourceLocation CommandLocEnd,
137                                            unsigned CommandID,
138                                            SourceLocation ArgLocBegin,
139                                            SourceLocation ArgLocEnd,
140                                            StringRef Arg);
141 
142   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
143                                             SourceLocation LocEnd,
144                                             StringRef CommandName);
145 
146   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
147                                             SourceLocation LocEnd,
148                                             unsigned CommandID);
149 
150   TextComment *actOnText(SourceLocation LocBegin,
151                          SourceLocation LocEnd,
152                          StringRef Text);
153 
154   VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
155                                                 unsigned CommandID);
156 
157   VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
158                                                    StringRef Text);
159 
160   void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
161                                 SourceLocation CloseNameLocBegin,
162                                 StringRef CloseName,
163                                 ArrayRef<VerbatimBlockLineComment *> Lines);
164 
165   VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
166                                          unsigned CommandID,
167                                          SourceLocation TextBegin,
168                                          StringRef Text);
169 
170   HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
171                                               StringRef TagName);
172 
173   void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
174                                ArrayRef<HTMLStartTagComment::Attribute> Attrs,
175                                SourceLocation GreaterLoc,
176                                bool IsSelfClosing);
177 
178   HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
179                                      SourceLocation LocEnd,
180                                      StringRef TagName);
181 
182   FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
183 
184   void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
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 
192   void checkDeprecatedCommand(const BlockCommandComment *Comment);
193 
194   void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
195 
196   void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
197 
198   void checkContainerDecl(const BlockCommandComment *Comment);
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.
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
212   /// pointer.
213   bool isFunctionOrBlockPointerVarLikeDecl();
214   bool isFunctionOrMethodVariadic();
215   bool isObjCMethodDecl();
216   bool isObjCPropertyDecl();
217   bool isTemplateOrSpecialization();
218   bool isRecordLikeDecl();
219   bool isClassOrStructDecl();
220   bool isUnionDecl();
221   bool isObjCInterfaceDecl();
222   bool isObjCProtocolDecl();
223   bool isClassTemplateDecl();
224   bool isFunctionTemplateDecl();
225 
226   ArrayRef<const ParmVarDecl *> getParamVars();
227 
228   /// Extract all important semantic information from
229   /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
230   void inspectThisDecl();
231 
232   /// Returns index of a function parameter with a given name.
233   unsigned resolveParmVarReference(StringRef Name,
234                                    ArrayRef<const ParmVarDecl *> ParamVars);
235 
236   /// Returns index of a function parameter with the name closest to a given
237   /// typo.
238   unsigned correctTypoInParmVarReference(StringRef Typo,
239                                          ArrayRef<const ParmVarDecl *> ParamVars);
240 
241   bool resolveTParamReference(StringRef Name,
242                               const TemplateParameterList *TemplateParameters,
243                               SmallVectorImpl<unsigned> *Position);
244 
245   StringRef correctTypoInTParamReference(
246                               StringRef Typo,
247                               const TemplateParameterList *TemplateParameters);
248 
249   InlineCommandComment::RenderKind
250   getInlineCommandRenderKind(StringRef Name) const;
251 };
252 
253 } // end namespace comments
254 } // end namespace clang
255 
256 #endif
257 
258