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
25namespace clang {
26namespace comments {
27
28/// Information about a single command.
29///
30/// When reordering, adding or removing members please update the corresponding
31/// TableGen backend.
32struct 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.
145class CommandTraits {
146public:
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
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
185private:
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

source code of clang/include/clang/AST/CommentCommandTraits.h