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

   1 //===--- CommentCommandTraits.h - Comment command properties ----*- 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 class that provides information about comment
  11 //  commands.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15
  16 #ifndef LLVM_CLANG_AST_COMMENTCOMMANDTRAITS_H
  17 #define LLVM_CLANG_AST_COMMENTCOMMANDTRAITS_H
  18
  19 #include "clang/Basic/CommentOptions.h"
  20 #include "clang/Basic/LLVM.h"
  21 #include "llvm/ADT/SmallVector.h"
  22 #include "llvm/ADT/StringRef.h"
  23 #include "llvm/Support/Allocator.h"
  24 #include "llvm/Support/ErrorHandling.h"
  25
  26 namespace clang {
  27 namespace comments {
  28
  29 /// Information about a single command.
  30 ///
  31 /// When reordering, adding or removing members please update the corresponding
  32 /// TableGen backend.
  33 struct CommandInfo {
  34   unsigned getID() const {
  35     return ID;
  36   }
  37
  38   const char *Name;
  39
  40   /// Name of the command that ends the verbatim block.
  41   const char *EndCommandName;
  42
  43   /// DRY definition of the number of bits used for a command ID.
  44   enum { NumCommandIDBits = 20 };
  45
  46   /// The ID of the command.
  47   unsigned ID : NumCommandIDBits;
  48
  49   /// Number of word-like arguments for a given block command, except for
  50   /// \\param and \\tparam commands -- these have special argument parsers.
  51   unsigned NumArgs : 4;
  52
  53   /// True if this command is a inline command (of any kind).
  54   unsigned IsInlineCommand : 1;
  55
  56   /// True if this command is a block command (of any kind).
  57   unsigned IsBlockCommand : 1;
  58
  59   /// True if this command is introducing a brief documentation
  60   /// paragraph (\or an alias).
  61   unsigned IsBriefCommand : 1;
  62
  63   /// True if this command is \\returns or an alias.
  64   unsigned IsReturnsCommand : 1;
  65
  66   /// True if this command is introducing documentation for a function
  67   /// parameter (\\param or an alias).
  68   unsigned IsParamCommand : 1;
  69
  70   /// True if this command is introducing documentation for
  71   /// a template parameter (\\tparam or an alias).
  72   unsigned IsTParamCommand : 1;
  73
  74   /// True if this command is \\throws or an alias.
  75   unsigned IsThrowsCommand : 1;
  76
  77   /// True if this command is \\deprecated or an alias.
  78   unsigned IsDeprecatedCommand : 1;
  79
  80   /// True if this is a \\headerfile-like command.
  81   unsigned IsHeaderfileCommand : 1;
  82
  83   /// True if we don't want to warn about this command being passed an empty
  84   /// paragraph.  Meaningful only for block commands.
  85   unsigned IsEmptyParagraphAllowed : 1;
  86
  87   /// True if this command is a verbatim-like block command.
  88   ///
  89   /// A verbatim-like block command eats every character (except line starting
  90   /// decorations) until matching end command is seen or comment end is hit.
  91   unsigned IsVerbatimBlockCommand : 1;
  92
  93   /// True if this command is an end command for a verbatim-like block.
  94   unsigned IsVerbatimBlockEndCommand : 1;
  95
  96   /// True if this command is a verbatim line command.
  97   ///
  98   /// A verbatim-like line command eats everything until a newline is seen or
  99   /// comment end is hit.
 100   unsigned IsVerbatimLineCommand : 1;
 101
 102   /// True if this command contains a declaration for the entity being
 103   /// documented.
 104   ///
 105   /// For example:
 106   /// \code
 107   ///   \fn void f(int a);
 108   /// \endcode
 109   unsigned IsDeclarationCommand : 1;
 110
 111   /// True if verbatim-like line command is a function declaration.
 112   unsigned IsFunctionDeclarationCommand : 1;
 113
 114   /// True if block command is further describing a container API; such
 115   /// as \@coclass, \@classdesign, etc.
 116   unsigned IsRecordLikeDetailCommand : 1;
 117
 118   /// True if block command is a container API; such as \@interface.
 119   unsigned IsRecordLikeDeclarationCommand : 1;
 120
 121   /// True if this command is unknown.  This \c CommandInfo object was
 122   /// created during parsing.
 123   unsigned IsUnknownCommand : 1;
 124 };
 125
 126 /// This class provides information about commands that can be used
 127 /// in comments.
 128 class CommandTraits {
 129 public:
 130   enum KnownCommandIDs {
 131 #define COMMENT_COMMAND(NAME) KCI_##NAME,
 132 #include "clang/AST/CommentCommandList.inc"
 133 #undef COMMENT_COMMAND
 134     KCI_Last
 135   };
 136
 137   CommandTraits(llvm::BumpPtrAllocator &Allocator,
 138                 const CommentOptions &CommentOptions);
 139
 140   void registerCommentOptions(const CommentOptions &CommentOptions);
 141
 142   /// \returns a CommandInfo object for a given command name or
 143   /// NULL if no CommandInfo object exists for this command.
 144   const CommandInfo *getCommandInfoOrNULL(StringRef Name) const;
 145
 146   const CommandInfo *getCommandInfo(StringRef Name) const {
 147     if (const CommandInfo *Info = getCommandInfoOrNULL(Name))
 148       return Info;
 149     llvm_unreachable("the command should be known");
 150   }
 151
 152   const CommandInfo *getTypoCorrectCommandInfo(StringRef Typo) const;
 153
 154   const CommandInfo *getCommandInfo(unsigned CommandID) const;
 155
 156   const CommandInfo *registerUnknownCommand(StringRef CommandName);
 157
 158   const CommandInfo *registerBlockCommand(StringRef CommandName);
 159
 160   /// \returns a CommandInfo object for a given command name or
 161   /// NULL if \c Name is not a builtin command.
 162   static const CommandInfo *getBuiltinCommandInfo(StringRef Name);
 163
 164   /// \returns a CommandInfo object for a given command ID or
 165   /// NULL if \c CommandID is not a builtin command.
 166   static const CommandInfo *getBuiltinCommandInfo(unsigned CommandID);
 167
 168 private:
 169   CommandTraits(const CommandTraits &) = delete;
 170   void operator=(const CommandTraits &) = delete;
 171
 172   const CommandInfo *getRegisteredCommandInfo(StringRef Name) const;
 173   const CommandInfo *getRegisteredCommandInfo(unsigned CommandID) const;
 174
 175   CommandInfo *createCommandInfoWithName(StringRef CommandName);
 176
 177   unsigned NextID;
 178
 179   /// Allocator for CommandInfo objects.
 180   llvm::BumpPtrAllocator &Allocator;
 181
 182   SmallVector<CommandInfo *, 4> RegisteredCommands;
 183 };
 184
 185 } // end namespace comments
 186 } // end namespace clang
 187
 188 #endif
 189