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_COMMENT_SEMA_H
  15 #define LLVM_CLANG_AST_COMMENT_SEMA_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 &) LLVM_DELETED_FUNCTION;
  35   void operator=(const Sema &) LLVM_DELETED_FUNCTION;
  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     size_t Size = Source.size();
  83     if (Size != 0) {
  84       T *Mem = Allocator.Allocate<T>(Size);
  85       std::uninitialized_copy(Source.begin(), Source.end(), Mem);
  86       return llvm::makeArrayRef(Mem, Size);
  87     } else
  88       return llvm::makeArrayRef(static_cast<T *>(NULL), 0);
  89   }
  90
  91   ParagraphComment *actOnParagraphComment(
  92       ArrayRef<InlineContentComment *> Content);
  93
  94   BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
  95                                               SourceLocation LocEnd,
  96                                               unsigned CommandID,
  97                                               CommandMarkerKind CommandMarker);
  98
  99   void actOnBlockCommandArgs(BlockCommandComment *Command,
 100                              ArrayRef<BlockCommandComment::Argument> Args);
 101
 102   void actOnBlockCommandFinish(BlockCommandComment *Command,
 103                                ParagraphComment *Paragraph);
 104
 105   ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
 106                                               SourceLocation LocEnd,
 107                                               unsigned CommandID,
 108                                               CommandMarkerKind CommandMarker);
 109
 110   void actOnParamCommandDirectionArg(ParamCommandComment *Command,
 111                                      SourceLocation ArgLocBegin,
 112                                      SourceLocation ArgLocEnd,
 113                                      StringRef Arg);
 114
 115   void actOnParamCommandParamNameArg(ParamCommandComment *Command,
 116                                      SourceLocation ArgLocBegin,
 117                                      SourceLocation ArgLocEnd,
 118                                      StringRef Arg);
 119
 120   void actOnParamCommandFinish(ParamCommandComment *Command,
 121                                ParagraphComment *Paragraph);
 122
 123   TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
 124                                                 SourceLocation LocEnd,
 125                                                 unsigned CommandID,
 126                                                 CommandMarkerKind CommandMarker);
 127
 128   void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
 129                                       SourceLocation ArgLocBegin,
 130                                       SourceLocation ArgLocEnd,
 131                                       StringRef Arg);
 132
 133   void actOnTParamCommandFinish(TParamCommandComment *Command,
 134                                 ParagraphComment *Paragraph);
 135
 136   InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
 137                                            SourceLocation CommandLocEnd,
 138                                            unsigned CommandID);
 139
 140   InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
 141                                            SourceLocation CommandLocEnd,
 142                                            unsigned CommandID,
 143                                            SourceLocation ArgLocBegin,
 144                                            SourceLocation ArgLocEnd,
 145                                            StringRef Arg);
 146
 147   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
 148                                             SourceLocation LocEnd,
 149                                             StringRef CommandName);
 150
 151   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
 152                                             SourceLocation LocEnd,
 153                                             unsigned CommandID);
 154
 155   TextComment *actOnText(SourceLocation LocBegin,
 156                          SourceLocation LocEnd,
 157                          StringRef Text);
 158
 159   VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
 160                                                 unsigned CommandID);
 161
 162   VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
 163                                                    StringRef Text);
 164
 165   void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
 166                                 SourceLocation CloseNameLocBegin,
 167                                 StringRef CloseName,
 168                                 ArrayRef<VerbatimBlockLineComment *> Lines);
 169
 170   VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
 171                                          unsigned CommandID,
 172                                          SourceLocation TextBegin,
 173                                          StringRef Text);
 174
 175   HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
 176                                               StringRef TagName);
 177
 178   void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
 179                                ArrayRef<HTMLStartTagComment::Attribute> Attrs,
 180                                SourceLocation GreaterLoc,
 181                                bool IsSelfClosing);
 182
 183   HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
 184                                      SourceLocation LocEnd,
 185                                      StringRef TagName);
 186
 187   FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
 188
 189   void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
 190
 191   void checkReturnsCommand(const BlockCommandComment *Command);
 192
 193   /// Emit diagnostics about duplicate block commands that should be
 194   /// used only once per comment, e.g., \\brief and \\returns.
 195   void checkBlockCommandDuplicate(const BlockCommandComment *Command);
 196
 197   void checkDeprecatedCommand(const BlockCommandComment *Comment);
 198
 199   void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
 200
 201   void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
 202
 203   void checkContainerDecl(const BlockCommandComment *Comment);
 204
 205   /// Resolve parameter names to parameter indexes in function declaration.
 206   /// Emit diagnostics about unknown parametrs.
 207   void resolveParamCommandIndexes(const FullComment *FC);
 208
 209   bool isFunctionDecl();
 210   bool isAnyFunctionDecl();
 211
 212   /// \returns \c true if declaration that this comment is attached to declares
 213   /// a function pointer.
 214   bool isFunctionPointerVarDecl();
 215   bool isFunctionOrMethodVariadic();
 216   bool isObjCMethodDecl();
 217   bool isObjCPropertyDecl();
 218   bool isTemplateOrSpecialization();
 219   bool isRecordLikeDecl();
 220   bool isClassOrStructDecl();
 221   bool isUnionDecl();
 222   bool isObjCInterfaceDecl();
 223   bool isObjCProtocolDecl();
 224   bool isClassTemplateDecl();
 225   bool isFunctionTemplateDecl();
 226
 227   ArrayRef<const ParmVarDecl *> getParamVars();
 228
 229   /// Extract all important semantic information from
 230   /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
 231   void inspectThisDecl();
 232
 233   /// Returns index of a function parameter with a given name.
 234   unsigned resolveParmVarReference(StringRef Name,
 235                                    ArrayRef<const ParmVarDecl *> ParamVars);
 236
 237   /// Returns index of a function parameter with the name closest to a given
 238   /// typo.
 239   unsigned correctTypoInParmVarReference(StringRef Typo,
 240                                          ArrayRef<const ParmVarDecl *> ParamVars);
 241
 242   bool resolveTParamReference(StringRef Name,
 243                               const TemplateParameterList *TemplateParameters,
 244                               SmallVectorImpl<unsigned> *Position);
 245
 246   StringRef correctTypoInTParamReference(
 247                               StringRef Typo,
 248                               const TemplateParameterList *TemplateParameters);
 249
 250   InlineCommandComment::RenderKind
 251   getInlineCommandRenderKind(StringRef Name) const;
 252 };
 253
 254 } // end namespace comments
 255 } // end namespace clang
 256
 257 #endif
 258