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 /// \brief 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 (\\brief 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 /// \brief 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 /// \brief 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 /// \brief True if this command is an end command for a verbatim-like block. 94 unsigned IsVerbatimBlockEndCommand : 1; 95 96 /// \brief 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 /// \brief 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 /// \brief True if verbatim-like line command is a function declaration. 112 unsigned IsFunctionDeclarationCommand : 1; 113 114 /// \brief True if block command is further describing a container API; such 115 /// as \@coclass, \@classdesign, etc. 116 unsigned IsRecordLikeDetailCommand : 1; 117 118 /// \brief True if block command is a container API; such as \@interface. 119 unsigned IsRecordLikeDeclarationCommand : 1; 120 121 /// \brief 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 190
