clang  10.0.0svn
CommentCommandTraits.h
Go to the documentation of this file.
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 
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.
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.
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.
112 
113  /// True if block command is further describing a container API; such
114  /// as \@coclass, \@classdesign, etc.
116 
117  /// True if block command is a container API; such as \@interface.
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.
128 public:
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,
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 
unsigned IsRecordLikeDeclarationCommand
True if block command is a container API; such as @interface.
unsigned IsThrowsCommand
True if this command is \throws or an alias.
const char * EndCommandName
Name of the command that ends the verbatim block.
Options for controlling comment parsing.
unsigned IsDeprecatedCommand
True if this command is \deprecated or an alias.
Information about a single command.
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified...
unsigned ID
The ID of the command.
unsigned IsVerbatimLineCommand
True if this command is a verbatim line command.
unsigned IsParamCommand
True if this command is introducing documentation for a function parameter (\param or an alias)...
unsigned IsEmptyParagraphAllowed
True if we don&#39;t want to warn about this command being passed an empty paragraph. ...
unsigned IsBriefCommand
True if this command is introducing a brief documentation paragraph ( an alias).
Defines the clang::CommentOptions interface.
unsigned IsTParamCommand
True if this command is introducing documentation for a template parameter (\tparam or an alias)...
This class provides information about commands that can be used in comments.
unsigned IsRecordLikeDetailCommand
True if block command is further describing a container API; such as @coclass, @classdesign, etc.
const CommandInfo * getCommandInfo(StringRef Name) const
unsigned IsFunctionDeclarationCommand
True if verbatim-like line command is a function declaration.
Dataflow Directional Tag Classes.
unsigned IsHeaderfileCommand
True if this is a \headerfile-like command.
unsigned IsVerbatimBlockCommand
True if this command is a verbatim-like block command.
unsigned IsVerbatimBlockEndCommand
True if this command is an end command for a verbatim-like block.
unsigned IsUnknownCommand
True if this command is unknown.
unsigned IsBlockCommand
True if this command is a block command (of any kind).
unsigned IsReturnsCommand
True if this command is \returns or an alias.
unsigned IsInlineCommand
True if this command is a inline command (of any kind).
unsigned NumArgs
Number of word-like arguments for a given block command, except for \param and \tparam commands – th...
unsigned IsDeclarationCommand
True if this command contains a declaration for the entity being documented.