contrib/llvm/tools/clang/include/clang/AST/CommentSema.h

   1 //===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 //  This file defines the semantic analysis class for Doxygen comments.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_CLANG_AST_COMMENTSEMA_H
  15 #define LLVM_CLANG_AST_COMMENTSEMA_H
  16
  17 #include "clang/AST/Comment.h"
  18 #include "clang/Basic/Diagnostic.h"
  19 #include "clang/Basic/SourceLocation.h"
  20 #include "llvm/ADT/ArrayRef.h"
  21 #include "llvm/ADT/StringMap.h"
  22 #include "llvm/ADT/StringRef.h"
  23 #include "llvm/Support/Allocator.h"
  24
  25 namespace clang {
  26 class Decl;
  27 class SourceMgr;
  28 class Preprocessor;
  29
  30 namespace comments {
  31 class CommandTraits;
  32
  33 class Sema {
  34   Sema(const Sema &) = delete;
  35   void operator=(const Sema &) = delete;
  36
  37   /// Allocator for AST nodes.
  38   llvm::BumpPtrAllocator &Allocator;
  39
  40   /// Source manager for the comment being parsed.
  41   const SourceManager &SourceMgr;
  42
  43   DiagnosticsEngine &Diags;
  44
  45   CommandTraits &Traits;
  46
  47   const Preprocessor *PP;
  48
  49   /// Information about the declaration this comment is attached to.
  50   DeclInfo *ThisDeclInfo;
  51
  52   /// Comment AST nodes that correspond to parameter names in
  53   /// \c TemplateParameters.
  54   ///
  55   /// Contains a valid value if \c DeclInfo->IsFilled is true.
  56   llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
  57
  58   /// AST node for the \\brief command and its aliases.
  59   const BlockCommandComment *BriefCommand;
  60
  61   /// AST node for the \\headerfile command.
  62   const BlockCommandComment *HeaderfileCommand;
  63
  64   DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
  65     return Diags.Report(Loc, DiagID);
  66   }
  67
  68   /// A stack of HTML tags that are currently open (not matched with closing
  69   /// tags).
  70   SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
  71
  72 public:
  73   Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
  74        DiagnosticsEngine &Diags, CommandTraits &Traits,
  75        const Preprocessor *PP);
  76
  77   void setDecl(const Decl *D);
  78
  79   /// Returns a copy of array, owned by Sema's allocator.
  80   template<typename T>
  81   ArrayRef<T> copyArray(ArrayRef<T> Source) {
  82     if (!Source.empty())
  83       return Source.copy(Allocator);
  84     return None;
  85   }
  86
  87   ParagraphComment *actOnParagraphComment(
  88       ArrayRef<InlineContentComment *> Content);
  89
  90   BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
  91                                               SourceLocation LocEnd,
  92                                               unsigned CommandID,
  93                                               CommandMarkerKind CommandMarker);
  94
  95   void actOnBlockCommandArgs(BlockCommandComment *Command,
  96                              ArrayRef<BlockCommandComment::Argument> Args);
  97
  98   void actOnBlockCommandFinish(BlockCommandComment *Command,
  99                                ParagraphComment *Paragraph);
 100
 101   ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
 102                                               SourceLocation LocEnd,
 103                                               unsigned CommandID,
 104                                               CommandMarkerKind CommandMarker);
 105
 106   void actOnParamCommandDirectionArg(ParamCommandComment *Command,
 107                                      SourceLocation ArgLocBegin,
 108                                      SourceLocation ArgLocEnd,
 109                                      StringRef Arg);
 110
 111   void actOnParamCommandParamNameArg(ParamCommandComment *Command,
 112                                      SourceLocation ArgLocBegin,
 113                                      SourceLocation ArgLocEnd,
 114                                      StringRef Arg);
 115
 116   void actOnParamCommandFinish(ParamCommandComment *Command,
 117                                ParagraphComment *Paragraph);
 118
 119   TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
 120                                                 SourceLocation LocEnd,
 121                                                 unsigned CommandID,
 122                                                 CommandMarkerKind CommandMarker);
 123
 124   void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
 125                                       SourceLocation ArgLocBegin,
 126                                       SourceLocation ArgLocEnd,
 127                                       StringRef Arg);
 128
 129   void actOnTParamCommandFinish(TParamCommandComment *Command,
 130                                 ParagraphComment *Paragraph);
 131
 132   InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
 133                                            SourceLocation CommandLocEnd,
 134                                            unsigned CommandID);
 135
 136   InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
 137                                            SourceLocation CommandLocEnd,
 138                                            unsigned CommandID,
 139                                            SourceLocation ArgLocBegin,
 140                                            SourceLocation ArgLocEnd,
 141                                            StringRef Arg);
 142
 143   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
 144                                             SourceLocation LocEnd,
 145                                             StringRef CommandName);
 146
 147   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
 148                                             SourceLocation LocEnd,
 149                                             unsigned CommandID);
 150
 151   TextComment *actOnText(SourceLocation LocBegin,
 152                          SourceLocation LocEnd,
 153                          StringRef Text);
 154
 155   VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
 156                                                 unsigned CommandID);
 157
 158   VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
 159                                                    StringRef Text);
 160
 161   void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
 162                                 SourceLocation CloseNameLocBegin,
 163                                 StringRef CloseName,
 164                                 ArrayRef<VerbatimBlockLineComment *> Lines);
 165
 166   VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
 167                                          unsigned CommandID,
 168                                          SourceLocation TextBegin,
 169                                          StringRef Text);
 170
 171   HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
 172                                               StringRef TagName);
 173
 174   void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
 175                                ArrayRef<HTMLStartTagComment::Attribute> Attrs,
 176                                SourceLocation GreaterLoc,
 177                                bool IsSelfClosing);
 178
 179   HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
 180                                      SourceLocation LocEnd,
 181                                      StringRef TagName);
 182
 183   FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
 184
 185   void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
 186
 187   void checkReturnsCommand(const BlockCommandComment *Command);
 188
 189   /// Emit diagnostics about duplicate block commands that should be
 190   /// used only once per comment, e.g., \\brief and \\returns.
 191   void checkBlockCommandDuplicate(const BlockCommandComment *Command);
 192
 193   void checkDeprecatedCommand(const BlockCommandComment *Comment);
 194
 195   void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
 196
 197   void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
 198
 199   void checkContainerDecl(const BlockCommandComment *Comment);
 200
 201   /// Resolve parameter names to parameter indexes in function declaration.
 202   /// Emit diagnostics about unknown parametrs.
 203   void resolveParamCommandIndexes(const FullComment *FC);
 204
 205   bool isFunctionDecl();
 206   bool isAnyFunctionDecl();
 207
 208   /// \returns \c true if declaration that this comment is attached to declares
 209   /// a function pointer.
 210   bool isFunctionPointerVarDecl();
 211   bool isFunctionOrMethodVariadic();
 212   bool isObjCMethodDecl();
 213   bool isObjCPropertyDecl();
 214   bool isTemplateOrSpecialization();
 215   bool isRecordLikeDecl();
 216   bool isClassOrStructDecl();
 217   bool isUnionDecl();
 218   bool isObjCInterfaceDecl();
 219   bool isObjCProtocolDecl();
 220   bool isClassTemplateDecl();
 221   bool isFunctionTemplateDecl();
 222
 223   ArrayRef<const ParmVarDecl *> getParamVars();
 224
 225   /// Extract all important semantic information from
 226   /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
 227   void inspectThisDecl();
 228
 229   /// Returns index of a function parameter with a given name.
 230   unsigned resolveParmVarReference(StringRef Name,
 231                                    ArrayRef<const ParmVarDecl *> ParamVars);
 232
 233   /// Returns index of a function parameter with the name closest to a given
 234   /// typo.
 235   unsigned correctTypoInParmVarReference(StringRef Typo,
 236                                          ArrayRef<const ParmVarDecl *> ParamVars);
 237
 238   bool resolveTParamReference(StringRef Name,
 239                               const TemplateParameterList *TemplateParameters,
 240                               SmallVectorImpl<unsigned> *Position);
 241
 242   StringRef correctTypoInTParamReference(
 243                               StringRef Typo,
 244                               const TemplateParameterList *TemplateParameters);
 245
 246   InlineCommandComment::RenderKind
 247   getInlineCommandRenderKind(StringRef Name) const;
 248 };
 249
 250 } // end namespace comments
 251 } // end namespace clang
 252
 253 #endif
 254