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 { |
33 | 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 &); |
156 | |
157 | void registerCommentOptions(const 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 | |
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 | |