CommentCommandTraits.h source code [clang_source_code/include/clang/AST/CommentCommandTraits.h]

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	unsigned IsInlineCommand : 1;
54
55	/// True if this command is a block command (of any kind).
56	unsigned IsBlockCommand : 1;
57
58	/// True if this command is introducing a brief documentation
59	/// paragraph (\or an alias).
60	unsigned IsBriefCommand : 1;
61
62	/// True if this command is \\returns or an alias.
63	unsigned IsReturnsCommand : 1;
64
65	/// True if this command is introducing documentation for a function
66	/// parameter (\\param or an alias).
67	unsigned IsParamCommand : 1;
68
69	/// True if this command is introducing documentation for
70	/// a template parameter (\\tparam or an alias).
71	unsigned IsTParamCommand : 1;
72
73	/// True if this command is \\throws or an alias.
74	unsigned IsThrowsCommand : 1;
75
76	/// True if this command is \\deprecated or an alias.
77	unsigned IsDeprecatedCommand : 1;
78
79	/// True if this is a \\headerfile-like command.
80	unsigned IsHeaderfileCommand : 1;
81
82	/// True if we don't want to warn about this command being passed an empty
83	/// paragraph. Meaningful only for block commands.
84	unsigned IsEmptyParagraphAllowed : 1;
85
86	/// True if this command is a verbatim-like block command.
87	///
88	/// A verbatim-like block command eats every character (except line starting
89	/// decorations) until matching end command is seen or comment end is hit.
90	unsigned IsVerbatimBlockCommand : 1;
91
92	/// True if this command is an end command for a verbatim-like block.
93	unsigned IsVerbatimBlockEndCommand : 1;
94
95	/// True if this command is a verbatim line command.
96	///
97	/// A verbatim-like line command eats everything until a newline is seen or
98	/// comment end is hit.
99	unsigned IsVerbatimLineCommand : 1;
100
101	/// True if this command contains a declaration for the entity being
102	/// documented.
103	///
104	/// For example:
105	/// \code
106	/// \fn void f(int a);
107	/// \endcode
108	unsigned IsDeclarationCommand : 1;
109
110	/// True if verbatim-like line command is a function declaration.
111	unsigned IsFunctionDeclarationCommand : 1;
112
113	/// True if block command is further describing a container API; such
114	/// as \@coclass, \@classdesign, etc.
115	unsigned IsRecordLikeDetailCommand : 1;
116
117	/// True if block command is a container API; such as \@interface.
118	unsigned IsRecordLikeDeclarationCommand : 1;
119
120	/// True if this command is unknown. This \c CommandInfo object was
121	/// created during parsing.
122	unsigned IsUnknownCommand : 1;
123	};
124
125	/// This class provides information about commands that can be used
126	/// in comments.
127	class CommandTraits {
128	public:
129	enum KnownCommandIDs {
130	#define COMMENT_COMMAND(NAME) KCI_##NAME,
131	#include "clang/AST/CommentCommandList.inc"
132	#undef COMMENT_COMMAND
133	KCI_Last
134	};
135
136	CommandTraits(llvm::BumpPtrAllocator &Allocator,
137	const CommentOptions &CommentOptions);
138
139	void registerCommentOptions(const CommentOptions &CommentOptions);
140
141	/// \returns a CommandInfo object for a given command name or
142	/// NULL if no CommandInfo object exists for this command.
143	const CommandInfo *getCommandInfoOrNULL(StringRef Name) const;
144
145	const CommandInfo *getCommandInfo(StringRef Name) const {
146	if (const CommandInfo *Info = getCommandInfoOrNULL(Name))
147	return Info;
148	llvm_unreachable("the command should be known");
149	}
150
151	const CommandInfo *getTypoCorrectCommandInfo(StringRef Typo) const;
152
153	const CommandInfo *getCommandInfo(unsigned CommandID) const;
154
155	const CommandInfo *registerUnknownCommand(StringRef CommandName);
156
157	const CommandInfo *registerBlockCommand(StringRef CommandName);
158
159	/// \returns a CommandInfo object for a given command name or
160	/// NULL if \c Name is not a builtin command.
161	static const CommandInfo *getBuiltinCommandInfo(StringRef Name);
162
163	/// \returns a CommandInfo object for a given command ID or
164	/// NULL if \c CommandID is not a builtin command.
165	static const CommandInfo *getBuiltinCommandInfo(unsigned CommandID);
166
167	private:
168	CommandTraits(const CommandTraits &) = delete;
169	void operator=(const CommandTraits &) = delete;
170
171	const CommandInfo *getRegisteredCommandInfo(StringRef Name) const;
172	const CommandInfo *getRegisteredCommandInfo(unsigned CommandID) const;
173
174	CommandInfo *createCommandInfoWithName(StringRef CommandName);
175
176	unsigned NextID;
177
178	/// Allocator for CommandInfo objects.
179	llvm::BumpPtrAllocator &Allocator;
180
181	SmallVector<CommandInfo *, 4> RegisteredCommands;
182	};
183
184	} // end namespace comments
185	} // end namespace clang
186
187	#endif
188
189