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 
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 
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 {
getIDCommandInfo34   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.
85   unsigned IsEmptyParagraphAllowed : 1;
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.
94   unsigned IsVerbatimBlockEndCommand : 1;
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.
112   unsigned IsFunctionDeclarationCommand : 1;
113 
114   /// \brief True if block command is further describing a container API; such
115   /// as \@coclass, \@classdesign, etc.
116   unsigned IsRecordLikeDetailCommand : 1;
117 
118   /// \brief True if block command is a container API; such as \@interface.
119   unsigned IsRecordLikeDeclarationCommand : 1;
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.
128 class CommandTraits {
129 public:
130   enum KnownCommandIDs {
131 #define COMMENT_COMMAND(NAME) KCI_##NAME,
132 #include "clang/AST/CommentCommandList.inc"
133 #undef COMMENT_COMMAND
134     KCI_Last
135   };
136 
137   CommandTraits(llvm::BumpPtrAllocator &Allocator,
138                 const CommentOptions &CommentOptions);
139 
140   void registerCommentOptions(const CommentOptions &CommentOptions);
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 
getCommandInfo(StringRef Name)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 
190