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 {
getIDCommandInfo33   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 
getCommandInfo(StringRef Name)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