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