CommentCommandTraits.h revision 62290ae569016345b79d4e11dd93abc300e5a681 
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
24namespace clang {
25namespace comments {
26
27/// This class provides informaiton about commands that can be used
28/// in comments.
29class CommandTraits {
30public:
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 BeginName 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 BeginName, 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
91private:
92  struct VerbatimBlockCommand {
93    StringRef BeginName;
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
112inline 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
123inline bool CommandTraits::isParamCommand(StringRef Name) const {
124  return Name == "param";
125}
126
127inline bool CommandTraits::isTParamCommand(StringRef Name) const {
128  return Name == "tparam" || // Doxygen
129         Name == "templatefield"; // HeaderDoc
130}
131
132inline bool CommandTraits::isBriefCommand(StringRef Name) const {
133  return Name == "brief" || Name == "short";
134}
135
136inline bool CommandTraits::isReturnsCommand(StringRef Name) const {
137  return Name == "returns" || Name == "return" || Name == "result";
138}
139
140inline unsigned CommandTraits::getBlockCommandNumArgs(StringRef Name) const {
141  return 0;
142}
143
144inline 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
157