Home | History | Annotate | Download | only in AST
      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 
     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   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 declaration.
    105   unsigned IsFunctionDeclarationCommand : 1;
    106 
    107   /// \brief True if block command is further describing a container API; such
    108   /// as \@coclass, \@classdesign, etc.
    109   unsigned IsRecordLikeDetailCommand : 1;
    110 
    111   /// \brief True if block command is a container API; such as \@interface.
    112   unsigned IsRecordLikeDeclarationCommand : 1;
    113 
    114   /// \brief True if this command is unknown.  This \c CommandInfo object was
    115   /// created during parsing.
    116   unsigned IsUnknownCommand : 1;
    117 };
    118 
    119 /// This class provides information about commands that can be used
    120 /// in comments.
    121 class CommandTraits {
    122 public:
    123   enum KnownCommandIDs {
    124 #define COMMENT_COMMAND(NAME) KCI_##NAME,
    125 #include "clang/AST/CommentCommandList.inc"
    126 #undef COMMENT_COMMAND
    127     KCI_Last
    128   };
    129 
    130   CommandTraits(llvm::BumpPtrAllocator &Allocator,
    131                 const CommentOptions &CommentOptions);
    132 
    133   void registerCommentOptions(const CommentOptions &CommentOptions);
    134 
    135   /// \returns a CommandInfo object for a given command name or
    136   /// NULL if no CommandInfo object exists for this command.
    137   const CommandInfo *getCommandInfoOrNULL(StringRef Name) const;
    138 
    139   const CommandInfo *getCommandInfo(StringRef Name) const {
    140     if (const CommandInfo *Info = getCommandInfoOrNULL(Name))
    141       return Info;
    142     llvm_unreachable("the command should be known");
    143   }
    144 
    145   const CommandInfo *getTypoCorrectCommandInfo(StringRef Typo) const;
    146 
    147   const CommandInfo *getCommandInfo(unsigned CommandID) const;
    148 
    149   const CommandInfo *registerUnknownCommand(StringRef CommandName);
    150 
    151   const CommandInfo *registerBlockCommand(StringRef CommandName);
    152 
    153   /// \returns a CommandInfo object for a given command name or
    154   /// NULL if \c Name is not a builtin command.
    155   static const CommandInfo *getBuiltinCommandInfo(StringRef Name);
    156 
    157   /// \returns a CommandInfo object for a given command ID or
    158   /// NULL if \c CommandID is not a builtin command.
    159   static const CommandInfo *getBuiltinCommandInfo(unsigned CommandID);
    160 
    161 private:
    162   CommandTraits(const CommandTraits &) LLVM_DELETED_FUNCTION;
    163   void operator=(const CommandTraits &) LLVM_DELETED_FUNCTION;
    164 
    165   const CommandInfo *getRegisteredCommandInfo(StringRef Name) const;
    166   const CommandInfo *getRegisteredCommandInfo(unsigned CommandID) const;
    167 
    168   CommandInfo *createCommandInfoWithName(StringRef CommandName);
    169 
    170   unsigned NextID;
    171 
    172   /// Allocator for CommandInfo objects.
    173   llvm::BumpPtrAllocator &Allocator;
    174 
    175   SmallVector<CommandInfo *, 4> RegisteredCommands;
    176 };
    177 
    178 } // end namespace comments
    179 } // end namespace clang
    180 
    181 #endif
    182 
    183