clang/AST/CommentSema.h

0001 //===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 //  This file defines the semantic analysis class for Doxygen comments.
0010 //
0011 //===----------------------------------------------------------------------===//
0012
0013 #ifndef LLVM_CLANG_AST_COMMENTSEMA_H
0014 #define LLVM_CLANG_AST_COMMENTSEMA_H
0015
0016 #include "clang/AST/Comment.h"
0017 #include "clang/Basic/Diagnostic.h"
0018 #include "clang/Basic/SourceLocation.h"
0019 #include "llvm/ADT/ArrayRef.h"
0020 #include "llvm/ADT/StringMap.h"
0021 #include "llvm/ADT/StringRef.h"
0022 #include "llvm/Support/Allocator.h"
0023
0024 namespace clang {
0025 class Decl;
0026 class SourceMgr;
0027 class Preprocessor;
0028
0029 namespace comments {
0030 class CommandTraits;
0031
0032 class Sema {
0033   Sema(const Sema &) = delete;
0034   void operator=(const Sema &) = delete;
0035
0036   /// Allocator for AST nodes.
0037   llvm::BumpPtrAllocator &Allocator;
0038
0039   /// Source manager for the comment being parsed.
0040   const SourceManager &SourceMgr;
0041
0042   DiagnosticsEngine &Diags;
0043
0044   CommandTraits &Traits;
0045
0046   const Preprocessor *PP;
0047
0048   /// Information about the declaration this comment is attached to.
0049   DeclInfo *ThisDeclInfo;
0050
0051   /// Comment AST nodes that correspond to parameter names in
0052   /// \c TemplateParameters.
0053   ///
0054   /// Contains a valid value if \c DeclInfo->IsFilled is true.
0055   llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
0056
0057   /// AST node for the \command and its aliases.
0058   const BlockCommandComment *BriefCommand;
0059
0060   /// AST node for the \\headerfile command.
0061   const BlockCommandComment *HeaderfileCommand;
0062
0063   DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
0064     return Diags.Report(Loc, DiagID);
0065   }
0066
0067   /// A stack of HTML tags that are currently open (not matched with closing
0068   /// tags).
0069   SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
0070
0071 public:
0072   Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
0073        DiagnosticsEngine &Diags, CommandTraits &Traits,
0074        const Preprocessor *PP);
0075
0076   void setDecl(const Decl *D);
0077
0078   /// Returns a copy of array, owned by Sema's allocator.
0079   template<typename T>
0080   ArrayRef<T> copyArray(ArrayRef<T> Source) {
0081     if (!Source.empty())
0082       return Source.copy(Allocator);
0083     return {};
0084   }
0085
0086   ParagraphComment *actOnParagraphComment(
0087       ArrayRef<InlineContentComment *> Content);
0088
0089   BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
0090                                               SourceLocation LocEnd,
0091                                               unsigned CommandID,
0092                                               CommandMarkerKind CommandMarker);
0093
0094   void actOnBlockCommandArgs(BlockCommandComment *Command,
0095                              ArrayRef<BlockCommandComment::Argument> Args);
0096
0097   void actOnBlockCommandFinish(BlockCommandComment *Command,
0098                                ParagraphComment *Paragraph);
0099
0100   ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
0101                                               SourceLocation LocEnd,
0102                                               unsigned CommandID,
0103                                               CommandMarkerKind CommandMarker);
0104
0105   void actOnParamCommandDirectionArg(ParamCommandComment *Command,
0106                                      SourceLocation ArgLocBegin,
0107                                      SourceLocation ArgLocEnd,
0108                                      StringRef Arg);
0109
0110   void actOnParamCommandParamNameArg(ParamCommandComment *Command,
0111                                      SourceLocation ArgLocBegin,
0112                                      SourceLocation ArgLocEnd,
0113                                      StringRef Arg);
0114
0115   void actOnParamCommandFinish(ParamCommandComment *Command,
0116                                ParagraphComment *Paragraph);
0117
0118   TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
0119                                                 SourceLocation LocEnd,
0120                                                 unsigned CommandID,
0121                                                 CommandMarkerKind CommandMarker);
0122
0123   void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
0124                                       SourceLocation ArgLocBegin,
0125                                       SourceLocation ArgLocEnd,
0126                                       StringRef Arg);
0127
0128   void actOnTParamCommandFinish(TParamCommandComment *Command,
0129                                 ParagraphComment *Paragraph);
0130
0131   InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
0132                                            SourceLocation CommandLocEnd,
0133                                            unsigned CommandID,
0134                                            ArrayRef<Comment::Argument> Args);
0135
0136   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
0137                                             SourceLocation LocEnd,
0138                                             StringRef CommandName);
0139
0140   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
0141                                             SourceLocation LocEnd,
0142                                             unsigned CommandID);
0143
0144   TextComment *actOnText(SourceLocation LocBegin,
0145                          SourceLocation LocEnd,
0146                          StringRef Text);
0147
0148   VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
0149                                                 unsigned CommandID);
0150
0151   VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
0152                                                    StringRef Text);
0153
0154   void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
0155                                 SourceLocation CloseNameLocBegin,
0156                                 StringRef CloseName,
0157                                 ArrayRef<VerbatimBlockLineComment *> Lines);
0158
0159   VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
0160                                          unsigned CommandID,
0161                                          SourceLocation TextBegin,
0162                                          StringRef Text);
0163
0164   HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
0165                                               StringRef TagName);
0166
0167   void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
0168                                ArrayRef<HTMLStartTagComment::Attribute> Attrs,
0169                                SourceLocation GreaterLoc,
0170                                bool IsSelfClosing);
0171
0172   HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
0173                                      SourceLocation LocEnd,
0174                                      StringRef TagName);
0175
0176   FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
0177
0178 private:
0179   void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
0180
0181   void checkReturnsCommand(const BlockCommandComment *Command);
0182
0183   /// Emit diagnostics about duplicate block commands that should be
0184   /// used only once per comment, e.g., \and \\returns.
0185   void checkBlockCommandDuplicate(const BlockCommandComment *Command);
0186
0187   void checkDeprecatedCommand(const BlockCommandComment *Comment);
0188
0189   void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
0190
0191   void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
0192
0193   void checkContainerDecl(const BlockCommandComment *Comment);
0194
0195   /// Resolve parameter names to parameter indexes in function declaration.
0196   /// Emit diagnostics about unknown parameters.
0197   void resolveParamCommandIndexes(const FullComment *FC);
0198
0199   /// \returns \c true if the declaration that this comment is attached to
0200   /// is a pointer to function/method/block type or has such a type.
0201   bool involvesFunctionType();
0202
0203   bool isFunctionDecl();
0204   bool isAnyFunctionDecl();
0205
0206   /// \returns \c true if declaration that this comment is attached to declares
0207   /// a function pointer.
0208   bool isFunctionPointerVarDecl();
0209   bool isFunctionOrMethodVariadic();
0210   bool isObjCMethodDecl();
0211   bool isObjCPropertyDecl();
0212   bool isTemplateOrSpecialization();
0213   bool isRecordLikeDecl();
0214   bool isClassOrStructDecl();
0215   /// \return \c true if the declaration that this comment is attached to
0216   /// declares either struct, class or tag typedef.
0217   bool isClassOrStructOrTagTypedefDecl();
0218   bool isUnionDecl();
0219   bool isObjCInterfaceDecl();
0220   bool isObjCProtocolDecl();
0221   bool isClassTemplateDecl();
0222   bool isFunctionTemplateDecl();
0223
0224   ArrayRef<const ParmVarDecl *> getParamVars();
0225
0226   /// Extract all important semantic information from
0227   /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
0228   void inspectThisDecl();
0229
0230   /// Returns index of a function parameter with a given name.
0231   unsigned resolveParmVarReference(StringRef Name,
0232                                    ArrayRef<const ParmVarDecl *> ParamVars);
0233
0234   /// Returns index of a function parameter with the name closest to a given
0235   /// typo.
0236   unsigned correctTypoInParmVarReference(StringRef Typo,
0237                                          ArrayRef<const ParmVarDecl *> ParamVars);
0238
0239   bool resolveTParamReference(StringRef Name,
0240                               const TemplateParameterList *TemplateParameters,
0241                               SmallVectorImpl<unsigned> *Position);
0242
0243   StringRef correctTypoInTParamReference(
0244                               StringRef Typo,
0245                               const TemplateParameterList *TemplateParameters);
0246
0247   InlineCommandRenderKind getInlineCommandRenderKind(StringRef Name) const;
0248 };
0249
0250 } // end namespace comments
0251 } // end namespace clang
0252
0253 #endif
0254