[llvm-branch-commits] [cfe-branch] r149061 - in /cfe/branches/tooling/include/clang/ASTMatchers: ASTMatchersInternal.h ASTMatchersMacros.h
Manuel Klimek
klimek at google.com
Thu Jan 26 05:41:33 PST 2012
Author: klimek
Date: Thu Jan 26 07:41:33 2012
New Revision: 149061
URL: http://llvm.org/viewvc/llvm-project?rev=149061&view=rev
Log:
Comment fixes.
Modified:
cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersInternal.h
cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersMacros.h
Modified: cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersInternal.h
URL: http://llvm.org/viewvc/llvm-project/cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersInternal.h?rev=149061&r1=149060&r2=149061&view=diff
==============================================================================
--- cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersInternal.h (original)
+++ cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersInternal.h Thu Jan 26 07:41:33 2012
@@ -69,27 +69,30 @@
/// the union of all bound nodes on the path from the root to a each leaf.
class BoundNodesTree {
public:
- /// A visitor interface to visit all BoundNodes results for a BoundNodesTree.
+ /// \brief A visitor interface to visit all BoundNodes results for a
+ /// BoundNodesTree.
class Visitor {
public:
virtual ~Visitor() {}
- /// Called multiple times during a single call to VisitMatches(...).
+ /// \brief Called multiple times during a single call to VisitMatches(...).
+ ///
/// 'BoundNodesView' contains the bound nodes for a single match.
virtual void VisitMatch(const BoundNodes& BoundNodesView) = 0;
};
BoundNodesTree();
- /// Create a BoundNodesTree from pre-filled maps of bindings.
+ /// \brief Create a BoundNodesTree from pre-filled maps of bindings.
BoundNodesTree(const std::map<std::string, const clang::Decl*>& DeclBindings,
const std::map<std::string, const clang::Stmt*>& StmtBindings,
const std::vector<BoundNodesTree> RecursiveBindings);
- /// Adds all bound nodes to bound_nodes_builder.
+ /// \brief Adds all bound nodes to bound_nodes_builder.
void CopyTo(BoundNodesTreeBuilder* Builder) const;
- /// Visits all matches that this BoundNodesTree represents.
+ /// \brief Visits all matches that this BoundNodesTree represents.
+ ///
/// The ownership of 'visitor' remains at the caller.
void VisitMatches(Visitor* ResultVisitor);
@@ -119,7 +122,8 @@
public:
BoundNodesTreeBuilder();
- /// Add a binding from an id to a node.
+ /// \brief Add a binding from an id to a node.
+ ///
/// FIXME: Add overloads for all AST base types.
/// @{
void SetBinding(const std::pair<const std::string,
@@ -128,10 +132,10 @@
const clang::Stmt*>& binding);
/// @}
- /// Adds a branch in the tree.
+ /// \brief Adds a branch in the tree.
void AddMatch(const BoundNodesTree& Bindings);
- /// Returns a BoundNodes object containing all current bindings.
+ /// \brief Returns a BoundNodes object containing all current bindings.
BoundNodesTree Build() const;
private:
@@ -196,25 +200,26 @@
template <typename T>
class Matcher {
public:
- /// Takes ownership of the provided implementation pointer.
+ /// \brief Takes ownership of the provided implementation pointer.
explicit Matcher(MatcherInterface<T> *Implementation)
: Implementation(Implementation) {}
- /// Forwards the call to the underlying MatcherInterface<T> pointer.
+ /// \brief Forwards the call to the underlying MatcherInterface<T> pointer.
bool Matches(const T &Node,
ASTMatchFinder *Finder,
BoundNodesTreeBuilder *Builder) const {
return Implementation->Matches(Node, Finder, Builder);
}
- /// Implicitly converts this object to a Matcher<Derived>; requires
- /// Derived to be derived from T.
+ /// \brief Implicitly converts this object to a Matcher<Derived>.
+ ///
+ /// Requires Derived to be derived from T.
template <typename Derived>
operator Matcher<Derived>() const {
return Matcher<Derived>(new ImplicitCastMatcher<Derived>(*this));
}
- /// Returns an ID that uniquely identifies the matcher.
+ /// \brief Returns an ID that uniquely identifies the matcher.
uint64_t GetID() const {
/// FIXME: Document the requirements this imposes on matcher
/// implementations (no new() implementation_ during a Matches()).
@@ -222,7 +227,7 @@
}
private:
- /// Allows conversion from Matcher<T> to Matcher<Derived> if Derived
+ /// \brief Allows conversion from Matcher<T> to Matcher<Derived> if Derived
/// is derived from T.
template <typename Derived>
class ImplicitCastMatcher : public MatcherInterface<Derived> {
@@ -243,16 +248,17 @@
llvm::IntrusiveRefCntPtr< MatcherInterface<T> > Implementation;
}; // class Matcher
-/// A convenient helper for creating a Matcher<T> without specifying
+/// \brief A convenient helper for creating a Matcher<T> without specifying
/// the template type argument.
template <typename T>
inline Matcher<T> MakeMatcher(MatcherInterface<T> *Implementation) {
return Matcher<T>(Implementation);
}
-/// Matches declarations for QualType and CallExpr. Type argument
-/// DeclMatcherT is required by PolymorphicMatcherWithParam1 but not
-/// actually used.
+/// \brief Matches declarations for QualType and CallExpr.
+///
+/// Type argument DeclMatcherT is required by PolymorphicMatcherWithParam1 but
+/// not actually used.
template <typename T, typename DeclMatcherT>
class HasDeclarationMatcher : public MatcherInterface<T> {
TOOLING_COMPILE_ASSERT((llvm::is_same< DeclMatcherT,
@@ -269,8 +275,8 @@
}
private:
- /// Extracts the CXXRecordDecl of a QualType and returns whether the inner
- /// matcher matches on it.
+ /// \brief Extracts the CXXRecordDecl of a QualType and returns whether the
+ /// inner matcher matches on it.
bool MatchesSpecialized(const clang::QualType &Node, ASTMatchFinder *Finder,
BoundNodesTreeBuilder *Builder) const {
/// FIXME: Add other ways to convert...
@@ -279,8 +285,8 @@
InnerMatcher.Matches(*NodeAsRecordDecl, Finder, Builder);
}
- /// Extracts the Decl of the callee of a CallExpr and returns whether the
- /// inner matcher matches on it.
+ /// \brief Extracts the Decl of the callee of a CallExpr and returns whether
+ /// the inner matcher matches on it.
bool MatchesSpecialized(const clang::CallExpr &Node, ASTMatchFinder *Finder,
BoundNodesTreeBuilder *Builder) const {
const clang::Decl *NodeAsDecl = Node.getCalleeDecl();
@@ -288,8 +294,8 @@
InnerMatcher.Matches(*NodeAsDecl, Finder, Builder);
}
- /// Extracts the Decl of the constructor call and returns whether the inner
- /// matcher matches on it.
+ /// \brief Extracts the Decl of the constructor call and returns whether the
+ /// inner matcher matches on it.
bool MatchesSpecialized(const clang::CXXConstructExpr &Node,
ASTMatchFinder *Finder,
BoundNodesTreeBuilder *Builder) const {
@@ -298,7 +304,7 @@
InnerMatcher.Matches(*NodeAsDecl, Finder, Builder);
}
- /// Extracts the Decl of the constructor ran by the new expression and
+ /// \brief Extracts the Decl of the constructor ran by the new expression and
/// returns whether the inner matcher matches on it.
bool MatchesSpecialized(const clang::CXXNewExpr& Node,
ASTMatchFinder* Finder,
@@ -311,7 +317,7 @@
const Matcher<clang::Decl> InnerMatcher;
};
-/// IsBaseType<T>::value is true if T is a "base" type in the AST
+/// \brief IsBaseType<T>::value is true if T is a "base" type in the AST
/// node class hierarchies (i.e. if T is Decl, Stmt, or QualType).
template <typename T>
struct IsBaseType {
@@ -322,7 +328,7 @@
template <typename T>
const bool IsBaseType<T>::value;
-/// Interface that can match any AST base node type and contains default
+/// \brief Interface that can match any AST base node type and contains default
/// implementations returning false.
class UntypedBaseMatcher {
public:
@@ -341,12 +347,12 @@
return false;
}
- /// Returns a unique ID for the matcher.
+ /// \brief Returns a unique ID for the matcher.
virtual uint64_t GetID() const = 0;
};
-/// An UntypedBaseMatcher that overwrites the Matches(...) method for node
-/// type T. T must be an AST base type.
+/// \brief An UntypedBaseMatcher that overwrites the Matches(...) method for
+/// node type T. T must be an AST base type.
template <typename T>
class TypedBaseMatcher : public UntypedBaseMatcher {
TOOLING_COMPILE_ASSERT(IsBaseType<T>::value,
@@ -356,16 +362,18 @@
: InnerMatcher(InnerMatcher) {}
using UntypedBaseMatcher::Matches;
- /// Implements UntypedBaseMatcher::Matches. Since T is guaranteed to
- /// be a "base" AST node type, this method is guaranteed to override
- /// one of the Matches() methods from UntypedBaseMatcher.
+ /// \brief Implements UntypedBaseMatcher::Matches.
+ ///
+ /// Since T is guaranteed to be a "base" AST node type, this method is
+ /// guaranteed to override one of the Matches() methods from
+ /// UntypedBaseMatcher.
virtual bool Matches(const T &Node,
ASTMatchFinder *Finder,
BoundNodesTreeBuilder *Builder) const {
return InnerMatcher.Matches(Node, Finder, Builder);
}
- /// Implements UntypedBaseMatcher::GetID.
+ /// \brief Implements UntypedBaseMatcher::GetID.
virtual uint64_t GetID() const {
return InnerMatcher.GetID();
}
@@ -374,9 +382,9 @@
Matcher<T> InnerMatcher;
};
+/// \brief Interface that allows matchers to traverse the AST.
/// FIXME: Find a better name.
///
-/// Interface that allows matchers to traverse the AST.
/// This provides two entry methods for each base node type in the AST:
/// - MatchesChildOf:
/// Matches a matcher on every child node of the given node. Returns true
@@ -386,7 +394,7 @@
/// if at least one descendant matched.
class ASTMatchFinder {
public:
- /// Defines how we descend a level in the AST when we pass
+ /// \brief Defines how we descend a level in the AST when we pass
/// through expressions.
enum TraversalKind {
/// Will traverse any child nodes.
@@ -395,7 +403,7 @@
TK_IgnoreImplicitCastsAndParentheses
};
- /// Defines how bindings are processed on recursive matches.
+ /// \brief Defines how bindings are processed on recursive matches.
enum BindKind {
/// Stop at the first match and only bind the first match.
BK_First,
@@ -405,9 +413,10 @@
virtual ~ASTMatchFinder() {}
- /// Returns true if the given class is directly or indirectly derived
- /// from a base type with the given name. A class is considered to
- /// be also derived from itself.
+ /// \brief Returns true if the given class is directly or indirectly derived
+ /// from a base type with the given name.
+ ///
+ /// A class is considered to be also derived from itself.
virtual bool ClassIsDerivedFrom(const clang::CXXRecordDecl *Declaration,
const std::string &BaseName) const = 0;
@@ -433,10 +442,12 @@
BindKind Bind) = 0;
};
-/// Converts a Matcher<T> to a matcher of desired type To by "adapting"
-/// a To into a T. The ArgumentAdapterT argument specifies how the
-/// adaptation is done. For example:
+/// \brief Converts a Matcher<T> to a matcher of desired type To by "adapting"
+/// a To into a T.
///
+/// The ArgumentAdapterT argument specifies how the adaptation is done.
+///
+/// For example:
/// ArgumentAdaptingMatcher<DynCastMatcher, T>(InnerMatcher);
/// returns a matcher that can be used where a Matcher<To> is required, if
/// To and T are in the same type hierarchy, and thus dyn_cast can be
@@ -461,7 +472,7 @@
const Matcher<T> InnerMatcher;
};
-/// A PolymorphicMatcherWithParamN<MatcherT, P1, ..., PN> object can be
+/// \brief A PolymorphicMatcherWithParamN<MatcherT, P1, ..., PN> object can be
/// created from N parameters p1, ..., pN (of type P1, ..., PN) and
/// used as a Matcher<T> where a MatcherT<T, P1, ..., PN>(p1, ..., pN)
/// can be constructed.
@@ -515,7 +526,7 @@
const P2 Param2;
};
-/// Matches any instance of the given NodeType.
+/// \brief Matches any instance of the given NodeType.
///
/// This is useful when a matcher syntactically requires a child matcher,
/// but the context doesn't care. See for example: True().
@@ -537,7 +548,7 @@
}
};
-/// Provides a MatcherInterface<T> for a Matcher<To> that matches if T is
+/// \brief Provides a MatcherInterface<T> for a Matcher<To> that matches if T is
/// dyn_cast'able into To and the given Matcher<To> matches on the dyn_cast'ed
/// node.
template <typename T, typename To>
@@ -558,7 +569,9 @@
const Matcher<To> InnerMatcher;
};
-/// Enables the user to pass a Matcher<clang::CXXMemberCallExpr> to Call().
+/// \brief Enables the user to pass a Matcher<clang::CXXMemberCallExpr> to
+/// Call().
+///
/// FIXME: Alternatives are using more specific methods than Call, like
/// MemberCall, or not using VariadicFunction for Call and overloading it.
template <>
@@ -569,13 +582,13 @@
new DynCastMatcher<clang::CallExpr, clang::CXXMemberCallExpr>(*this));
}
-/// Matcher<T> that wraps an inner Matcher<T> and binds the matched node to
-/// an ID if the inner matcher matches on the node.
+/// \brief Matcher<T> that wraps an inner Matcher<T> and binds the matched node
+/// to an ID if the inner matcher matches on the node.
template <typename T>
class IdMatcher : public MatcherInterface<T> {
public:
- /// Creates an IdMatcher that binds to 'ID' if 'InnerMatcher' matches the
- /// node.
+ /// \brief Creates an IdMatcher that binds to 'ID' if 'InnerMatcher' matches
+ /// the node.
IdMatcher(const std::string &ID, const Matcher<T> &InnerMatcher)
: ID(ID), InnerMatcher(InnerMatcher) {}
@@ -594,9 +607,10 @@
const Matcher<T> InnerMatcher;
};
-/// Matches nodes of type T that have child nodes of type ChildT for
-/// which a specified child matcher matches. ChildT must be an AST base
-/// type.
+/// \brief Matches nodes of type T that have child nodes of type ChildT for
+/// which a specified child matcher matches.
+///
+/// ChildT must be an AST base type.
template <typename T, typename ChildT>
class HasMatcher : public MatcherInterface<T> {
TOOLING_COMPILE_ASSERT(IsBaseType<ChildT>::value,
@@ -644,7 +658,8 @@
const TypedBaseMatcher<ChildT> ChildMatcher;
};
-/// Matches nodes of type T if the given Matcher<T> does not match.
+/// \brief Matches nodes of type T if the given Matcher<T> does not match.
+///
/// Type argument MatcherT is required by PolymorphicMatcherWithParam1
/// but not actually used. It will always be instantiated with a type
/// convertible to Matcher<T>.
@@ -664,8 +679,9 @@
const Matcher<T> InnerMatcher;
};
-/// Matches nodes of type T for which both provided matchers
-/// match. Type arguments MatcherT1 and MatcherT2 are required by
+/// \brief Matches nodes of type T for which both provided matchers match.
+///
+/// Type arguments MatcherT1 and MatcherT2 are required by
/// PolymorphicMatcherWithParam2 but not actually used. They will
/// always be instantiated with types convertible to Matcher<T>.
template <typename T, typename MatcherT1, typename MatcherT2>
@@ -686,8 +702,10 @@
const Matcher<T> InnerMatcher2;
};
-/// Matches nodes of type T for which at least one of the two provided
-/// matchers matches. Type arguments MatcherT1 and MatcherT2 are
+/// \brief Matches nodes of type T for which at least one of the two provided
+/// matchers matches.
+///
+/// Type arguments MatcherT1 and MatcherT2 are
/// required by PolymorphicMatcherWithParam2 but not actually
/// used. They will always be instantiated with types convertible to
/// Matcher<T>.
@@ -709,7 +727,7 @@
const Matcher<T> InnertMatcher2;
};
-/// Creates a Matcher<T> that matches if
+/// \brief Creates a Matcher<T> that matches if
/// T is dyn_cast'able into InnerT and all inner matchers match.
template<typename T, typename InnerT>
Matcher<T> MakeDynCastAllOfComposite(
@@ -727,8 +745,9 @@
return ArgumentAdaptingMatcher<DynCastMatcher, InnerT>(InnerMatcher);
}
-/// Matches nodes of type T that have at least one descendant node of
+/// \brief Matches nodes of type T that have at least one descendant node of
/// type DescendantT for which the given inner matcher matches.
+///
/// DescendantT must be an AST base type.
template <typename T, typename DescendantT>
class HasDescendantMatcher : public MatcherInterface<T> {
@@ -751,6 +770,7 @@
/// \brief Matches nodes of type T that have at least one descendant node of
/// type DescendantT for which the given inner matcher matches.
+///
/// DescendantT must be an AST base type.
/// As opposed to HasDescendantMatcher, ForEachDescendantMatcher will match
/// for each descendant node that matches instead of only for the first.
@@ -774,8 +794,8 @@
const TypedBaseMatcher<DescendantT> DescendantMatcher;
};
-/// Matches on nodes that have a getValue() method if getValue() equals the
-/// value the ValueEqualsMatcher was constructed with.
+/// \brief Matches on nodes that have a getValue() method if getValue() equals
+/// the value the ValueEqualsMatcher was constructed with.
template <typename T, typename ValueT>
class ValueEqualsMatcher : public SingleNodeMatcherInterface<T> {
TOOLING_COMPILE_ASSERT((llvm::is_base_of<clang::CharacterLiteral, T>::value ||
@@ -809,7 +829,7 @@
}
};
-/// Matches on template instantiations for FunctionDecl, VarDecl or
+/// \brief Matches on template instantiations for FunctionDecl, VarDecl or
/// CXXRecordDecl nodes.
template <typename T>
class IsTemplateInstantiationMatcher : public MatcherInterface<T> {
@@ -843,7 +863,7 @@
}
};
-/// A VariadicDynCastAllOfMatcher<SourceT, TargetT> object is a
+/// \brief A VariadicDynCastAllOfMatcher<SourceT, TargetT> object is a
/// variadic functor that takes a number of Matcher<TargetT> and returns a
/// Matcher<SourceT> that matches TargetT nodes that are matched by all of the
/// given matchers, if SourceT can be dynamically casted into TargetT.
Modified: cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersMacros.h
URL: http://llvm.org/viewvc/llvm-project/cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersMacros.h?rev=149061&r1=149060&r2=149061&view=diff
==============================================================================
--- cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersMacros.h (original)
+++ cfe/branches/tooling/include/clang/ASTMatchers/ASTMatchersMacros.h Thu Jan 26 07:41:33 2012
@@ -25,11 +25,11 @@
#ifndef LLVM_CLANG_AST_MATCHERS_AST_MATCHERS_MACROS_H
#define LLVM_CLANG_AST_MATCHERS_AST_MATCHERS_MACROS_H
-/// AST_MATCHER(Type, DefineMatcher) { ... }
-///
+/// \brief AST_MATCHER(Type, DefineMatcher) { ... }
/// defines a zero parameter function named DefineMatcher() that returns a
-/// Matcher<Type> object. The code between the curly braces has access
-/// to the following variables:
+/// Matcher<Type> object.
+///
+/// The code between the curly braces has access to the following variables:
///
/// Node: the AST node being matched; its type is Type.
/// Finder: an ASTMatchFinder*.
@@ -55,11 +55,11 @@
const Type &Node, ASTMatchFinder *Finder, \
BoundNodesTreeBuilder *Builder) const
-/// AST_MATCHER_P(Type, DefineMatcher, ParamType, Param) { ... }
-///
+/// \brief AST_MATCHER_P(Type, DefineMatcher, ParamType, Param) { ... }
/// defines a single-parameter function named DefineMatcher() that returns a
-/// Matcher<Type> object. The code between the curly braces has access
-/// to the following variables:
+/// Matcher<Type> object.
+///
+/// The code between the curly braces has access to the following variables:
///
/// Node: the AST node being matched; its type is Type.
/// Param: the parameter passed to the function; its type
@@ -90,12 +90,12 @@
const Type &Node, ASTMatchFinder *Finder, \
BoundNodesTreeBuilder *Builder) const
-/// AST_MATCHER_P2(Type, DefineMatcher, ParamType1, Param1, ParamType2, Param2)
-/// { ... }
-///
+/// \brief AST_MATCHER_P2(
+/// Type, DefineMatcher, ParamType1, Param1, ParamType2, Param2) { ... }
/// defines a two-parameter function named DefineMatcher() that returns a
-/// Matcher<Type> object. The code between the curly braces has access
-/// to the following variables:
+/// Matcher<Type> object.
+///
+/// The code between the curly braces has access to the following variables:
///
/// Node: the AST node being matched; its type is Type.
/// Param1, Param2: the parameters passed to the function; their types
@@ -131,10 +131,11 @@
const Type &Node, ASTMatchFinder *Finder, \
BoundNodesTreeBuilder *Builder) const
-/// AST_POLYMORPHIC_MATCHER_P(DefineMatcher, ParamType, Param) { ... }
-///
+/// \brief AST_POLYMORPHIC_MATCHER_P(DefineMatcher, ParamType, Param) { ... }
/// defines a single-parameter function named DefineMatcher() that is
-/// polymorphic in the return type. The variables are the same as for
+/// polymorphic in the return type.
+///
+/// The variables are the same as for
/// AST_MATCHER_P, with the addition of NodeType, which specifies the node type
/// of the matcher Matcher<NodeType> returned by the function matcher().
///
@@ -167,11 +168,12 @@
const NodeType &Node, ASTMatchFinder *Finder, \
BoundNodesTreeBuilder *Builder) const
-/// AST_POLYMORPHIC_MATCHER_P2(
+/// \brief AST_POLYMORPHIC_MATCHER_P2(
/// DefineMatcher, ParamType1, Param1, ParamType2, Param2) { ... }
-///
/// defines a two-parameter function named matcher() that is polymorphic in
-/// the return type. The variables are the same as for AST_MATCHER_P2, with the
+/// the return type.
+///
+/// The variables are the same as for AST_MATCHER_P2, with the
/// addition of NodeType, which specifies the node type of the matcher
/// Matcher<NodeType> returned by the function DefineMatcher().
#define AST_POLYMORPHIC_MATCHER_P2( \
More information about the llvm-branch-commits
mailing list