clang/AST/CommentCommandTraits.h

0001 //===--- CommentCommandTraits.h - Comment command properties ----*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 //  This file defines the class that provides information about comment
0010 //  commands.
0011 //
0012 //===----------------------------------------------------------------------===//
0013
0014
0015 #ifndef LLVM_CLANG_AST_COMMENTCOMMANDTRAITS_H
0016 #define LLVM_CLANG_AST_COMMENTCOMMANDTRAITS_H
0017
0018 #include "clang/Basic/CommentOptions.h"
0019 #include "clang/Basic/LLVM.h"
0020 #include "llvm/ADT/SmallVector.h"
0021 #include "llvm/ADT/StringRef.h"
0022 #include "llvm/Support/Allocator.h"
0023 #include "llvm/Support/ErrorHandling.h"
0024
0025 namespace clang {
0026 namespace comments {
0027
0028 /// Information about a single command.
0029 ///
0030 /// When reordering, adding or removing members please update the corresponding
0031 /// TableGen backend.
0032 struct CommandInfo {
0033   unsigned getID() const {
0034     return ID;
0035   }
0036
0037   const char *Name;
0038
0039   /// Name of the command that ends the verbatim block.
0040   const char *EndCommandName;
0041
0042   /// DRY definition of the number of bits used for a command ID.
0043   enum { NumCommandIDBits = 20 };
0044
0045   /// The ID of the command.
0046   unsigned ID : NumCommandIDBits;
0047
0048   /// Number of word-like arguments for a given block command, except for
0049   /// \\param and \\tparam commands -- these have special argument parsers.
0050   unsigned NumArgs : 4;
0051
0052   /// True if this command is a inline command (of any kind).
0053   LLVM_PREFERRED_TYPE(bool)
0054   unsigned IsInlineCommand : 1;
0055
0056   /// True if this command is a block command (of any kind).
0057   LLVM_PREFERRED_TYPE(bool)
0058   unsigned IsBlockCommand : 1;
0059
0060   /// True if this command is introducing a brief documentation
0061   /// paragraph (\or an alias).
0062   LLVM_PREFERRED_TYPE(bool)
0063   unsigned IsBriefCommand : 1;
0064
0065   /// True if this command is \\returns or an alias.
0066   LLVM_PREFERRED_TYPE(bool)
0067   unsigned IsReturnsCommand : 1;
0068
0069   /// True if this command is introducing documentation for a function
0070   /// parameter (\\param or an alias).
0071   LLVM_PREFERRED_TYPE(bool)
0072   unsigned IsParamCommand : 1;
0073
0074   /// True if this command is introducing documentation for
0075   /// a template parameter (\\tparam or an alias).
0076   LLVM_PREFERRED_TYPE(bool)
0077   unsigned IsTParamCommand : 1;
0078
0079   /// True if this command is \\throws or an alias.
0080   LLVM_PREFERRED_TYPE(bool)
0081   unsigned IsThrowsCommand : 1;
0082
0083   /// True if this command is \\deprecated or an alias.
0084   LLVM_PREFERRED_TYPE(bool)
0085   unsigned IsDeprecatedCommand : 1;
0086
0087   /// True if this is a \\headerfile-like command.
0088   LLVM_PREFERRED_TYPE(bool)
0089   unsigned IsHeaderfileCommand : 1;
0090
0091   /// True if this is a \\par command.
0092   LLVM_PREFERRED_TYPE(bool)
0093   unsigned IsParCommand : 1;
0094
0095   /// True if we don't want to warn about this command being passed an empty
0096   /// paragraph.  Meaningful only for block commands.
0097   LLVM_PREFERRED_TYPE(bool)
0098   unsigned IsEmptyParagraphAllowed : 1;
0099
0100   /// True if this command is a verbatim-like block command.
0101   ///
0102   /// A verbatim-like block command eats every character (except line starting
0103   /// decorations) until matching end command is seen or comment end is hit.
0104   LLVM_PREFERRED_TYPE(bool)
0105   unsigned IsVerbatimBlockCommand : 1;
0106
0107   /// True if this command is an end command for a verbatim-like block.
0108   LLVM_PREFERRED_TYPE(bool)
0109   unsigned IsVerbatimBlockEndCommand : 1;
0110
0111   /// True if this command is a verbatim line command.
0112   ///
0113   /// A verbatim-like line command eats everything until a newline is seen or
0114   /// comment end is hit.
0115   LLVM_PREFERRED_TYPE(bool)
0116   unsigned IsVerbatimLineCommand : 1;
0117
0118   /// True if this command contains a declaration for the entity being
0119   /// documented.
0120   ///
0121   /// For example:
0122   /// \code
0123   ///   \fn void f(int a);
0124   /// \endcode
0125   LLVM_PREFERRED_TYPE(bool)
0126   unsigned IsDeclarationCommand : 1;
0127
0128   /// True if verbatim-like line command is a function declaration.
0129   LLVM_PREFERRED_TYPE(bool)
0130   unsigned IsFunctionDeclarationCommand : 1;
0131
0132   /// True if block command is further describing a container API; such
0133   /// as \@coclass, \@classdesign, etc.
0134   LLVM_PREFERRED_TYPE(bool)
0135   unsigned IsRecordLikeDetailCommand : 1;
0136
0137   /// True if block command is a container API; such as \@interface.
0138   LLVM_PREFERRED_TYPE(bool)
0139   unsigned IsRecordLikeDeclarationCommand : 1;
0140
0141   /// True if this command is unknown.  This \c CommandInfo object was
0142   /// created during parsing.
0143   LLVM_PREFERRED_TYPE(bool)
0144   unsigned IsUnknownCommand : 1;
0145 };
0146
0147 /// This class provides information about commands that can be used
0148 /// in comments.
0149 class CommandTraits {
0150 public:
0151   enum KnownCommandIDs {
0152 #define COMMENT_COMMAND(NAME) KCI_##NAME,
0153 #include "clang/AST/CommentCommandList.inc"
0154 #undef COMMENT_COMMAND
0155     KCI_Last
0156   };
0157
0158   CommandTraits(llvm::BumpPtrAllocator &Allocator,
0159                 const CommentOptions &CommentOptions);
0160
0161   void registerCommentOptions(const CommentOptions &CommentOptions);
0162
0163   /// \returns a CommandInfo object for a given command name or
0164   /// NULL if no CommandInfo object exists for this command.
0165   const CommandInfo *getCommandInfoOrNULL(StringRef Name) const;
0166
0167   const CommandInfo *getCommandInfo(StringRef Name) const {
0168     if (const CommandInfo *Info = getCommandInfoOrNULL(Name))
0169       return Info;
0170     llvm_unreachable("the command should be known");
0171   }
0172
0173   const CommandInfo *getTypoCorrectCommandInfo(StringRef Typo) const;
0174
0175   const CommandInfo *getCommandInfo(unsigned CommandID) const;
0176
0177   const CommandInfo *registerUnknownCommand(StringRef CommandName);
0178
0179   const CommandInfo *registerBlockCommand(StringRef CommandName);
0180
0181   /// \returns a CommandInfo object for a given command name or
0182   /// NULL if \c Name is not a builtin command.
0183   static const CommandInfo *getBuiltinCommandInfo(StringRef Name);
0184
0185   /// \returns a CommandInfo object for a given command ID or
0186   /// NULL if \c CommandID is not a builtin command.
0187   static const CommandInfo *getBuiltinCommandInfo(unsigned CommandID);
0188
0189 private:
0190   CommandTraits(const CommandTraits &) = delete;
0191   void operator=(const CommandTraits &) = delete;
0192
0193   const CommandInfo *getRegisteredCommandInfo(StringRef Name) const;
0194   const CommandInfo *getRegisteredCommandInfo(unsigned CommandID) const;
0195
0196   CommandInfo *createCommandInfoWithName(StringRef CommandName);
0197
0198   unsigned NextID;
0199
0200   /// Allocator for CommandInfo objects.
0201   llvm::BumpPtrAllocator &Allocator;
0202
0203   SmallVector<CommandInfo *, 4> RegisteredCommands;
0204 };
0205
0206 } // end namespace comments
0207 } // end namespace clang
0208
0209 #endif
0210