contrib/llvm/tools/clang/include/clang/AST/CommentCommandTraits.h

   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/LLVM.h"
  20 #include "llvm/ADT/StringRef.h"
  21 #include "llvm/ADT/SmallVector.h"
  22 #include "llvm/ADT/StringSwitch.h"
  23
  24 namespace clang {
  25 namespace comments {
  26
  27 /// This class provides informaiton about commands that can be used
  28 /// in comments.
  29 class CommandTraits {
  30 public:
  31   CommandTraits() { }
  32
  33   /// \brief Check if a given command is a verbatim-like block command.
  34   ///
  35   /// A verbatim-like block command eats every character (except line starting
  36   /// decorations) until matching end command is seen or comment end is hit.
  37   ///
  38   /// \param StartName name of the command that starts the verbatim block.
  39   /// \param [out] EndName name of the command that ends the verbatim block.
  40   ///
  41   /// \returns true if a given command is a verbatim block command.
  42   bool isVerbatimBlockCommand(StringRef StartName, StringRef &EndName) const;
  43
  44   /// \brief Register a new verbatim block command.
  45   void addVerbatimBlockCommand(StringRef StartName, StringRef EndName);
  46
  47   /// \brief Check if a given command is a verbatim line command.
  48   ///
  49   /// A verbatim-like line command eats everything until a newline is seen or
  50   /// comment end is hit.
  51   bool isVerbatimLineCommand(StringRef Name) const;
  52
  53   /// \brief Check if a given command is a command that contains a declaration
  54   /// for the entity being documented.
  55   ///
  56   /// For example:
  57   /// \code
  58   ///   \fn void f(int a);
  59   /// \endcode
  60   bool isDeclarationCommand(StringRef Name) const;
  61
  62   /// \brief Register a new verbatim line command.
  63   void addVerbatimLineCommand(StringRef Name);
  64
  65   /// \brief Check if a given command is a block command (of any kind).
  66   bool isBlockCommand(StringRef Name) const;
  67
  68   /// \brief Check if a given command is introducing documentation for
  69   /// a function parameter (\\param or an alias).
  70   bool isParamCommand(StringRef Name) const;
  71
  72   /// \brief Check if a given command is introducing documentation for
  73   /// a template parameter (\\tparam or an alias).
  74   bool isTParamCommand(StringRef Name) const;
  75
  76   /// \brief Check if a given command is introducing a brief documentation
  77   /// paragraph (\\brief or an alias).
  78   bool isBriefCommand(StringRef Name) const;
  79
  80   /// \brief Check if a given command is \\brief or an alias.
  81   bool isReturnsCommand(StringRef Name) const;
  82
  83   /// \returns the number of word-like arguments for a given block command,
  84   /// except for \\param and \\tparam commands -- these have special argument
  85   /// parsers.
  86   unsigned getBlockCommandNumArgs(StringRef Name) const;
  87
  88   /// \brief Check if a given command is a inline command (of any kind).
  89   bool isInlineCommand(StringRef Name) const;
  90
  91 private:
  92   struct VerbatimBlockCommand {
  93     StringRef StartName;
  94     StringRef EndName;
  95   };
  96
  97   typedef SmallVector<VerbatimBlockCommand, 4> VerbatimBlockCommandVector;
  98
  99   /// Registered additional verbatim-like block commands.
 100   VerbatimBlockCommandVector VerbatimBlockCommands;
 101
 102   struct VerbatimLineCommand {
 103     StringRef Name;
 104   };
 105
 106   typedef SmallVector<VerbatimLineCommand, 4> VerbatimLineCommandVector;
 107
 108   /// Registered verbatim-like line commands.
 109   VerbatimLineCommandVector VerbatimLineCommands;
 110 };
 111
 112 inline bool CommandTraits::isBlockCommand(StringRef Name) const {
 113   return isBriefCommand(Name) || isReturnsCommand(Name) ||
 114       isParamCommand(Name) || isTParamCommand(Name) ||
 115       llvm::StringSwitch<bool>(Name)
 116       .Case("author", true)
 117       .Case("authors", true)
 118       .Case("pre", true)
 119       .Case("post", true)
 120       .Default(false);
 121 }
 122
 123 inline bool CommandTraits::isParamCommand(StringRef Name) const {
 124   return Name == "param";
 125 }
 126
 127 inline bool CommandTraits::isTParamCommand(StringRef Name) const {
 128   return Name == "tparam" || // Doxygen
 129          Name == "templatefield"; // HeaderDoc
 130 }
 131
 132 inline bool CommandTraits::isBriefCommand(StringRef Name) const {
 133   return Name == "brief" || Name == "short";
 134 }
 135
 136 inline bool CommandTraits::isReturnsCommand(StringRef Name) const {
 137   return Name == "returns" || Name == "return" || Name == "result";
 138 }
 139
 140 inline unsigned CommandTraits::getBlockCommandNumArgs(StringRef Name) const {
 141   return 0;
 142 }
 143
 144 inline bool CommandTraits::isInlineCommand(StringRef Name) const {
 145   return llvm::StringSwitch<bool>(Name)
 146       .Case("b", true)
 147       .Cases("c", "p", true)
 148       .Cases("a", "e", "em", true)
 149       .Default(false);
 150 }
 151
 152 } // end namespace comments
 153 } // end namespace clang
 154
 155 #endif
 156