CommentCommandTraits.h revision 2a268f2629b49958427e8eb02f2c3d565be71acc 
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_COMMENT_COMMAND_TRAITS_H
17#define LLVM_CLANG_AST_COMMENT_COMMAND_TRAITS_H
18
19#include "clang/Basic/CommentOptions.h"
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
26namespace clang {
27namespace comments {
28
29/// \brief Information about a single command.
30///
31/// When reordering, adding or removing members please update the corresponding
32/// TableGen backend.
33struct 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  unsigned ID : 8;
44
45  /// Number of word-like arguments for a given block command, except for
46  /// \\param and \\tparam commands -- these have special argument parsers.
47  unsigned NumArgs : 4;
48
49  /// True if this command is a inline command (of any kind).
50  unsigned IsInlineCommand : 1;
51
52  /// True if this command is a block command (of any kind).
53  unsigned IsBlockCommand : 1;
54
55  /// True if this command is introducing a brief documentation
56  /// paragraph (\\brief or an alias).
57  unsigned IsBriefCommand : 1;
58
59  /// True if this command is \\returns or an alias.
60  unsigned IsReturnsCommand : 1;
61
62  /// True if this command is introducing documentation for a function
63  /// parameter (\\param or an alias).
64  unsigned IsParamCommand : 1;
65
66  /// True if this command is introducing documentation for
67  /// a template parameter (\\tparam or an alias).
68  unsigned IsTParamCommand : 1;
69
70  /// True if this command is \\deprecated or an alias.
71  unsigned IsDeprecatedCommand : 1;
72
73  /// \brief True if this is a \\headerfile-like command.
74  unsigned IsHeaderfileCommand : 1;
75
76  /// True if we don't want to warn about this command being passed an empty
77  /// paragraph.  Meaningful only for block commands.
78  unsigned IsEmptyParagraphAllowed : 1;
79
80  /// \brief True if this command is a verbatim-like block command.
81  ///
82  /// A verbatim-like block command eats every character (except line starting
83  /// decorations) until matching end command is seen or comment end is hit.
84  unsigned IsVerbatimBlockCommand : 1;
85
86  /// \brief True if this command is an end command for a verbatim-like block.
87  unsigned IsVerbatimBlockEndCommand : 1;
88
89  /// \brief True if this command is a verbatim line command.
90  ///
91  /// A verbatim-like line command eats everything until a newline is seen or
92  /// comment end is hit.
93  unsigned IsVerbatimLineCommand : 1;
94
95  /// \brief True if this command contains a declaration for the entity being
96  /// documented.
97  ///
98  /// For example:
99  /// \code
100  ///   \fn void f(int a);
101  /// \endcode
102  unsigned IsDeclarationCommand : 1;
103
104  /// \brief True if verbatim-like line command is a function declaraton.
105  unsigned IsFunctionDeclarationCommand : 1;
106
107  /// \brief True if this command is unknown.  This \c CommandInfo object was
108  /// created during parsing.
109  unsigned IsUnknownCommand : 1;
110};
111
112/// This class provides information about commands that can be used
113/// in comments.
114class CommandTraits {
115public:
116  enum KnownCommandIDs {
117#define COMMENT_COMMAND(NAME) KCI_##NAME,
118#include "clang/AST/CommentCommandList.inc"
119#undef COMMENT_COMMAND
120    KCI_Last
121  };
122
123  CommandTraits(llvm::BumpPtrAllocator &Allocator,
124                const CommentOptions &CommentOptions);
125
126  void registerCommentOptions(const CommentOptions &CommentOptions);
127
128  /// \returns a CommandInfo object for a given command name or
129  /// NULL if no CommandInfo object exists for this command.
130  const CommandInfo *getCommandInfoOrNULL(StringRef Name) const;
131
132  const CommandInfo *getCommandInfo(StringRef Name) const {
133    if (const CommandInfo *Info = getCommandInfoOrNULL(Name))
134      return Info;
135    llvm_unreachable("the command should be known");
136  }
137
138  const CommandInfo *getCommandInfo(unsigned CommandID) const;
139
140  const CommandInfo *registerUnknownCommand(StringRef CommandName);
141
142  const CommandInfo *registerBlockCommand(StringRef CommandName);
143
144  /// \returns a CommandInfo object for a given command name or
145  /// NULL if \c Name is not a builtin command.
146  static const CommandInfo *getBuiltinCommandInfo(StringRef Name);
147
148  /// \returns a CommandInfo object for a given command ID or
149  /// NULL if \c CommandID is not a builtin command.
150  static const CommandInfo *getBuiltinCommandInfo(unsigned CommandID);
151
152private:
153  CommandTraits(const CommandTraits &) LLVM_DELETED_FUNCTION;
154  void operator=(const CommandTraits &) LLVM_DELETED_FUNCTION;
155
156  const CommandInfo *getRegisteredCommandInfo(StringRef Name) const;
157  const CommandInfo *getRegisteredCommandInfo(unsigned CommandID) const;
158
159  CommandInfo *createCommandInfoWithName(StringRef CommandName);
160
161  unsigned NextID;
162
163  /// Allocator for CommandInfo objects.
164  llvm::BumpPtrAllocator &Allocator;
165
166  SmallVector<CommandInfo *, 4> RegisteredCommands;
167};
168
169} // end namespace comments
170} // end namespace clang
171
172#endif
173
174