clang  3.9.0
CommentCommandTraits.h
Go to the documentation of this file.
1 //===--- CommentCommandTraits.h - Comment command properties ----*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file defines the class that provides information about comment
11 // commands.
12 //
13 //===----------------------------------------------------------------------===//
14 
15 
16 #ifndef LLVM_CLANG_AST_COMMENTCOMMANDTRAITS_H
17 #define LLVM_CLANG_AST_COMMENTCOMMANDTRAITS_H
18 
20 #include "clang/Basic/LLVM.h"
21 #include "llvm/ADT/SmallVector.h"
22 #include "llvm/ADT/StringRef.h"
23 #include "llvm/Support/Allocator.h"
24 #include "llvm/Support/ErrorHandling.h"
25 
26 namespace clang {
27 namespace comments {
28 
29 /// \brief Information about a single command.
30 ///
31 /// When reordering, adding or removing members please update the corresponding
32 /// TableGen backend.
33 struct CommandInfo {
34  unsigned getID() const {
35  return ID;
36  }
37 
38  const char *Name;
39 
40  /// Name of the command that ends the verbatim block.
41  const char *EndCommandName;
42 
43  /// DRY definition of the number of bits used for a command ID.
44  enum { NumCommandIDBits = 20 };
45 
46  /// The ID of the command.
47  unsigned ID : NumCommandIDBits;
48 
49  /// Number of word-like arguments for a given block command, except for
50  /// \\param and \\tparam commands -- these have special argument parsers.
51  unsigned NumArgs : 4;
52 
53  /// True if this command is a inline command (of any kind).
54  unsigned IsInlineCommand : 1;
55 
56  /// True if this command is a block command (of any kind).
57  unsigned IsBlockCommand : 1;
58 
59  /// True if this command is introducing a brief documentation
60  /// paragraph (\\brief or an alias).
61  unsigned IsBriefCommand : 1;
62 
63  /// True if this command is \\returns or an alias.
64  unsigned IsReturnsCommand : 1;
65 
66  /// True if this command is introducing documentation for a function
67  /// parameter (\\param or an alias).
68  unsigned IsParamCommand : 1;
69 
70  /// True if this command is introducing documentation for
71  /// a template parameter (\\tparam or an alias).
72  unsigned IsTParamCommand : 1;
73 
74  /// True if this command is \\throws or an alias.
75  unsigned IsThrowsCommand : 1;
76 
77  /// True if this command is \\deprecated or an alias.
78  unsigned IsDeprecatedCommand : 1;
79 
80  /// \brief True if this is a \\headerfile-like command.
81  unsigned IsHeaderfileCommand : 1;
82 
83  /// True if we don't want to warn about this command being passed an empty
84  /// paragraph. Meaningful only for block commands.
86 
87  /// \brief True if this command is a verbatim-like block command.
88  ///
89  /// A verbatim-like block command eats every character (except line starting
90  /// decorations) until matching end command is seen or comment end is hit.
91  unsigned IsVerbatimBlockCommand : 1;
92 
93  /// \brief True if this command is an end command for a verbatim-like block.
95 
96  /// \brief True if this command is a verbatim line command.
97  ///
98  /// A verbatim-like line command eats everything until a newline is seen or
99  /// comment end is hit.
100  unsigned IsVerbatimLineCommand : 1;
101 
102  /// \brief True if this command contains a declaration for the entity being
103  /// documented.
104  ///
105  /// For example:
106  /// \code
107  /// \fn void f(int a);
108  /// \endcode
109  unsigned IsDeclarationCommand : 1;
110 
111  /// \brief True if verbatim-like line command is a function declaration.
113 
114  /// \brief True if block command is further describing a container API; such
115  /// as \@coclass, \@classdesign, etc.
117 
118  /// \brief True if block command is a container API; such as \@interface.
120 
121  /// \brief True if this command is unknown. This \c CommandInfo object was
122  /// created during parsing.
123  unsigned IsUnknownCommand : 1;
124 };
125 
126 /// This class provides information about commands that can be used
127 /// in comments.
129 public:
131 #define COMMENT_COMMAND(NAME) KCI_##NAME,
132 #include "clang/AST/CommentCommandList.inc"
133 #undef COMMENT_COMMAND
135  };
136 
137  CommandTraits(llvm::BumpPtrAllocator &Allocator,
139 
141 
142  /// \returns a CommandInfo object for a given command name or
143  /// NULL if no CommandInfo object exists for this command.
144  const CommandInfo *getCommandInfoOrNULL(StringRef Name) const;
145 
146  const CommandInfo *getCommandInfo(StringRef Name) const {
147  if (const CommandInfo *Info = getCommandInfoOrNULL(Name))
148  return Info;
149  llvm_unreachable("the command should be known");
150  }
151 
152  const CommandInfo *getTypoCorrectCommandInfo(StringRef Typo) const;
153 
154  const CommandInfo *getCommandInfo(unsigned CommandID) const;
155 
156  const CommandInfo *registerUnknownCommand(StringRef CommandName);
157 
158  const CommandInfo *registerBlockCommand(StringRef CommandName);
159 
160  /// \returns a CommandInfo object for a given command name or
161  /// NULL if \c Name is not a builtin command.
162  static const CommandInfo *getBuiltinCommandInfo(StringRef Name);
163 
164  /// \returns a CommandInfo object for a given command ID or
165  /// NULL if \c CommandID is not a builtin command.
166  static const CommandInfo *getBuiltinCommandInfo(unsigned CommandID);
167 
168 private:
169  CommandTraits(const CommandTraits &) = delete;
170  void operator=(const CommandTraits &) = delete;
171 
172  const CommandInfo *getRegisteredCommandInfo(StringRef Name) const;
173  const CommandInfo *getRegisteredCommandInfo(unsigned CommandID) const;
174 
175  CommandInfo *createCommandInfoWithName(StringRef CommandName);
176 
177  unsigned NextID;
178 
179  /// Allocator for CommandInfo objects.
180  llvm::BumpPtrAllocator &Allocator;
181 
182  SmallVector<CommandInfo *, 4> RegisteredCommands;
183 };
184 
185 } // end namespace comments
186 } // end namespace clang
187 
188 #endif
189 
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.
const CommandInfo * getCommandInfo(StringRef Name) const
class LLVM_ALIGNAS(8) DependentTemplateSpecializationType const IdentifierInfo * Name
Represents a template specialization type whose template cannot be resolved, e.g. ...
Definition: Type.h:4549
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't want to warn about this command being passed an empty paragraph. ...
unsigned IsBriefCommand
True if this command is introducing a brief documentation paragraph (\brief or an alias)...
Defines the clang::CommentOptions interface.
const CommandInfo * getCommandInfoOrNULL(StringRef Name) const
const CommandInfo * getTypoCorrectCommandInfo(StringRef Typo) const
unsigned IsTParamCommand
True if this command is introducing documentation for a template parameter (\tparam or an alias)...
const CommandInfo * registerBlockCommand(StringRef CommandName)
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.
void registerCommentOptions(const CommentOptions &CommentOptions)
unsigned IsFunctionDeclarationCommand
True if verbatim-like line command is a function declaration.
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.
StringRef Typo
static const CommandInfo * getBuiltinCommandInfo(StringRef Name)
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.
const CommandInfo * registerUnknownCommand(StringRef CommandName)
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 – the...
CommandTraits(llvm::BumpPtrAllocator &Allocator, const CommentOptions &CommentOptions)
unsigned IsDeclarationCommand
True if this command contains a declaration for the entity being documented.