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/Basic/Diagnostic.h"
  18 #include "clang/Basic/SourceLocation.h"
  19 #include "clang/AST/Comment.h"
  20 #include "llvm/ADT/ArrayRef.h"
  21 #include "llvm/ADT/StringRef.h"
  22 #include "llvm/ADT/StringMap.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 \\returns command and its aliases.
  62   const BlockCommandComment *ReturnsCommand;
  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
  98   void actOnBlockCommandArgs(BlockCommandComment *Command,
  99                              ArrayRef<BlockCommandComment::Argument> Args);
 100
 101   void actOnBlockCommandFinish(BlockCommandComment *Command,
 102                                ParagraphComment *Paragraph);
 103
 104   ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
 105                                               SourceLocation LocEnd,
 106                                               unsigned CommandID);
 107
 108   void actOnParamCommandDirectionArg(ParamCommandComment *Command,
 109                                      SourceLocation ArgLocBegin,
 110                                      SourceLocation ArgLocEnd,
 111                                      StringRef Arg);
 112
 113   void actOnParamCommandParamNameArg(ParamCommandComment *Command,
 114                                      SourceLocation ArgLocBegin,
 115                                      SourceLocation ArgLocEnd,
 116                                      StringRef Arg);
 117
 118   void actOnParamCommandFinish(ParamCommandComment *Command,
 119                                ParagraphComment *Paragraph);
 120
 121   TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
 122                                                 SourceLocation LocEnd,
 123                                                 unsigned CommandID);
 124
 125   void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
 126                                       SourceLocation ArgLocBegin,
 127                                       SourceLocation ArgLocEnd,
 128                                       StringRef Arg);
 129
 130   void actOnTParamCommandFinish(TParamCommandComment *Command,
 131                                 ParagraphComment *Paragraph);
 132
 133   InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
 134                                            SourceLocation CommandLocEnd,
 135                                            unsigned CommandID);
 136
 137   InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
 138                                            SourceLocation CommandLocEnd,
 139                                            unsigned CommandID,
 140                                            SourceLocation ArgLocBegin,
 141                                            SourceLocation ArgLocEnd,
 142                                            StringRef Arg);
 143
 144   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
 145                                             SourceLocation LocEnd,
 146                                             StringRef CommandName);
 147
 148   InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
 149                                             SourceLocation LocEnd,
 150                                             unsigned CommandID);
 151
 152   TextComment *actOnText(SourceLocation LocBegin,
 153                          SourceLocation LocEnd,
 154                          StringRef Text);
 155
 156   VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
 157                                                 unsigned CommandID);
 158
 159   VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
 160                                                    StringRef Text);
 161
 162   void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
 163                                 SourceLocation CloseNameLocBegin,
 164                                 StringRef CloseName,
 165                                 ArrayRef<VerbatimBlockLineComment *> Lines);
 166
 167   VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
 168                                          unsigned CommandID,
 169                                          SourceLocation TextBegin,
 170                                          StringRef Text);
 171
 172   HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
 173                                               StringRef TagName);
 174
 175   void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
 176                                ArrayRef<HTMLStartTagComment::Attribute> Attrs,
 177                                SourceLocation GreaterLoc,
 178                                bool IsSelfClosing);
 179
 180   HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
 181                                      SourceLocation LocEnd,
 182                                      StringRef TagName);
 183
 184   FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
 185
 186   void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
 187
 188   void checkReturnsCommand(const BlockCommandComment *Command);
 189
 190   /// Emit diagnostics about duplicate block commands that should be
 191   /// used only once per comment, e.g., \\brief and \\returns.
 192   void checkBlockCommandDuplicate(const BlockCommandComment *Command);
 193
 194   void checkDeprecatedCommand(const BlockCommandComment *Comment);
 195
 196   /// Resolve parameter names to parameter indexes in function declaration.
 197   /// Emit diagnostics about unknown parametrs.
 198   void resolveParamCommandIndexes(const FullComment *FC);
 199
 200   bool isFunctionDecl();
 201   bool isTemplateOrSpecialization();
 202
 203   ArrayRef<const ParmVarDecl *> getParamVars();
 204
 205   /// Extract all important semantic information from
 206   /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
 207   void inspectThisDecl();
 208
 209   /// Returns index of a function parameter with a given name.
 210   unsigned resolveParmVarReference(StringRef Name,
 211                                    ArrayRef<const ParmVarDecl *> ParamVars);
 212
 213   /// Returns index of a function parameter with the name closest to a given
 214   /// typo.
 215   unsigned correctTypoInParmVarReference(StringRef Typo,
 216                                          ArrayRef<const ParmVarDecl *> ParamVars);
 217
 218   bool resolveTParamReference(StringRef Name,
 219                               const TemplateParameterList *TemplateParameters,
 220                               SmallVectorImpl<unsigned> *Position);
 221
 222   StringRef correctTypoInTParamReference(
 223                               StringRef Typo,
 224                               const TemplateParameterList *TemplateParameters);
 225
 226   InlineCommandComment::RenderKind
 227   getInlineCommandRenderKind(StringRef Name) const;
 228 };
 229
 230 } // end namespace comments
 231 } // end namespace clang
 232
 233 #endif
 234