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 this is a \\par command. 92 LLVM_PREFERRED_TYPE(bool) 93 unsigned IsParCommand : 1; 94 95 /// True if we don't want to warn about this command being passed an empty 96 /// paragraph. Meaningful only for block commands. 97 LLVM_PREFERRED_TYPE(bool) 98 unsigned IsEmptyParagraphAllowed : 1; 99 100 /// True if this command is a verbatim-like block command. 101 /// 102 /// A verbatim-like block command eats every character (except line starting 103 /// decorations) until matching end command is seen or comment end is hit. 104 LLVM_PREFERRED_TYPE(bool) 105 unsigned IsVerbatimBlockCommand : 1; 106 107 /// True if this command is an end command for a verbatim-like block. 108 LLVM_PREFERRED_TYPE(bool) 109 unsigned IsVerbatimBlockEndCommand : 1; 110 111 /// True if this command is a verbatim line command. 112 /// 113 /// A verbatim-like line command eats everything until a newline is seen or 114 /// comment end is hit. 115 LLVM_PREFERRED_TYPE(bool) 116 unsigned IsVerbatimLineCommand : 1; 117 118 /// True if this command contains a declaration for the entity being 119 /// documented. 120 /// 121 /// For example: 122 /// \code 123 /// \fn void f(int a); 124 /// \endcode 125 LLVM_PREFERRED_TYPE(bool) 126 unsigned IsDeclarationCommand : 1; 127 128 /// True if verbatim-like line command is a function declaration. 129 LLVM_PREFERRED_TYPE(bool) 130 unsigned IsFunctionDeclarationCommand : 1; 131 132 /// True if block command is further describing a container API; such 133 /// as \@coclass, \@classdesign, etc. 134 LLVM_PREFERRED_TYPE(bool) 135 unsigned IsRecordLikeDetailCommand : 1; 136 137 /// True if block command is a container API; such as \@interface. 138 LLVM_PREFERRED_TYPE(bool) 139 unsigned IsRecordLikeDeclarationCommand : 1; 140 141 /// True if this command is unknown. This \c CommandInfo object was 142 /// created during parsing. 143 LLVM_PREFERRED_TYPE(bool) 144 unsigned IsUnknownCommand : 1; 145 }; 146 147 /// This class provides information about commands that can be used 148 /// in comments. 149 class CommandTraits { 150 public: 151 enum KnownCommandIDs { 152 #define COMMENT_COMMAND(NAME) KCI_##NAME, 153 #include "clang/AST/CommentCommandList.inc" 154 #undef COMMENT_COMMAND 155 KCI_Last 156 }; 157 158 CommandTraits(llvm::BumpPtrAllocator &Allocator, 159 const CommentOptions &CommentOptions); 160 161 void registerCommentOptions(const CommentOptions &CommentOptions); 162 163 /// \returns a CommandInfo object for a given command name or 164 /// NULL if no CommandInfo object exists for this command. 165 const CommandInfo *getCommandInfoOrNULL(StringRef Name) const; 166 getCommandInfo(StringRef Name)167 const CommandInfo *getCommandInfo(StringRef Name) const { 168 if (const CommandInfo *Info = getCommandInfoOrNULL(Name)) 169 return Info; 170 llvm_unreachable("the command should be known"); 171 } 172 173 const CommandInfo *getTypoCorrectCommandInfo(StringRef Typo) const; 174 175 const CommandInfo *getCommandInfo(unsigned CommandID) const; 176 177 const CommandInfo *registerUnknownCommand(StringRef CommandName); 178 179 const CommandInfo *registerBlockCommand(StringRef CommandName); 180 181 /// \returns a CommandInfo object for a given command name or 182 /// NULL if \c Name is not a builtin command. 183 static const CommandInfo *getBuiltinCommandInfo(StringRef Name); 184 185 /// \returns a CommandInfo object for a given command ID or 186 /// NULL if \c CommandID is not a builtin command. 187 static const CommandInfo *getBuiltinCommandInfo(unsigned CommandID); 188 189 private: 190 CommandTraits(const CommandTraits &) = delete; 191 void operator=(const CommandTraits &) = delete; 192 193 const CommandInfo *getRegisteredCommandInfo(StringRef Name) const; 194 const CommandInfo *getRegisteredCommandInfo(unsigned CommandID) const; 195 196 CommandInfo *createCommandInfoWithName(StringRef CommandName); 197 198 unsigned NextID; 199 200 /// Allocator for CommandInfo objects. 201 llvm::BumpPtrAllocator &Allocator; 202 203 SmallVector<CommandInfo *, 4> RegisteredCommands; 204 }; 205 206 } // end namespace comments 207 } // end namespace clang 208 209 #endif 210 211