From 0389269a7d038b7399aa50272d4cb43a0e1a8b26 Mon Sep 17 00:00:00 2001 From: Manuel Klimek Date: Mon, 24 Feb 2014 10:40:22 +0000 Subject: [PATCH] Fix AST matcher documentation for overloaded matchers. Before this patch we would only use the fist occurance of a matcher function in the documentation, for example leaving out hasType(Matcher). llvm-svn: 202019 --- clang/docs/LibASTMatchersReference.html | 121 +++++++++++++++++++----- clang/docs/tools/dump_ast_matchers.py | 4 +- 2 files changed, 98 insertions(+), 27 deletions(-) diff --git a/clang/docs/LibASTMatchersReference.html b/clang/docs/LibASTMatchersReference.html index 314c89932ae0..ce922598135b 100644 --- a/clang/docs/LibASTMatchersReference.html +++ b/clang/docs/LibASTMatchersReference.html @@ -2043,24 +2043,6 @@ Usable as: Any Matcher -Matcher<*>forEachMatcher<*> -
Matches AST nodes that have child AST nodes that match the
-provided matcher.
-
-Example matches X, Y (matcher = recordDecl(forEach(recordDecl(hasName("X")))
-  class X {};  Matches X, because X::X is a class of name X inside X.
-  class Y { class X {}; };
-  class Z { class Y { class X {}; }; };  Does not match Z.
-
-ChildT must be an AST base type.
-
-As opposed to 'has', 'forEach' will cause a match for each result that
-matches instead of only on the first one.
-
-Usable as: Any Matcher
-
- - Matcher<*>forEachDescendantMatcher<*> 
Matches AST nodes that have descendant AST nodes that match the
 provided matcher.
@@ -2085,17 +2067,20 @@ Usable as: Any Matcher
-Matcher<*>hasMatcher<*> -
Matches AST nodes that have child AST nodes that match the
+Matcher<*>forEachMatcher<*>
+
Matches AST nodes that have child AST nodes that match the
 provided matcher.
 
-Example matches X, Y (matcher = recordDecl(has(recordDecl(hasName("X")))
+Example matches X, Y (matcher = recordDecl(forEach(recordDecl(hasName("X")))
   class X {};  Matches X, because X::X is a class of name X inside X.
   class Y { class X {}; };
   class Z { class Y { class X {}; }; };  Does not match Z.
 
 ChildT must be an AST base type.
 
+As opposed to 'has', 'forEach' will cause a match for each result that
+matches instead of only on the first one.
+
 Usable as: Any Matcher
 

 
@@ -2129,6 +2114,21 @@ Usable as: Any Matcher
+Matcher<*>hasMatcher<*> +
Matches AST nodes that have child AST nodes that match the
+provided matcher.
+
+Example matches X, Y (matcher = recordDecl(has(recordDecl(hasName("X")))
+  class X {};  Matches X, because X::X is a class of name X inside X.
+  class Y { class X {}; };
+  class Z { class Y { class X {}; }; };  Does not match Z.
+
+ChildT must be an AST base type.
+
+Usable as: Any Matcher
+
+ + Matcher<*>hasParentMatcher<*> 
Matches AST nodes that have a parent that matches the provided
 matcher.
@@ -2403,6 +2403,10 @@ matches 'int x' in
+Matcher<CXXMemberCallExpr>onImplicitObjectArgumentMatcher<Expr> InnerMatcher +

+
+
 Matcher<CXXMemberCallExpr>onMatcher<Expr> InnerMatcher
 
Matches on the implicit object argument of a member call expression.
 
@@ -2414,15 +2418,17 @@ FIXME: Overload to allow directly matching types?
 

 
 
-Matcher<CXXMemberCallExpr>onImplicitObjectArgumentMatcher<Expr> InnerMatcher
-

-
-
 Matcher<CXXMemberCallExpr>thisPointerTypeMatcher<Decl> InnerMatcher
 
Overloaded to match the type's declaration.
 

 
 
+Matcher<CXXMemberCallExpr>thisPointerTypeMatcher<QualType> InnerMatcher
+
Matches if the expression's type either matches the specified
+matcher, or is a pointer to a type that matches the InnerMatcher.
+

+
+
 Matcher<CXXMethodDecl>ofClassMatcher<CXXRecordDecl> InnerMatcher
 
Matches the class declaration that the given method declaration
 belongs to.
@@ -2491,6 +2497,24 @@ Example matches y.x() (matcher = callExpr(callee(methodDecl(hasName("x")))))
 

 
 
+Matcher<CallExpr>calleeMatcher<Stmt> InnerMatcher
+
Matches if the call expression's callee expression matches.
+
+Given
+  class Y { void x() { this->x(); x(); Y y; y.x(); } };
+  void f() { f(); }
+callExpr(callee(expr()))
+  matches this->x(), x(), y.x(), f()
+with callee(...)
+  matching this->x, x, y.x, f respectively
+
+Note: Callee cannot take the more general internal::Matcher<Expr>
+because this introduces ambiguous overloads with calls to Callee taking a
+internal::Matcher<Decl>, as the matcher hierarchy is purely
+implemented in terms of implicit casts.
+

+
+
 Matcher<CallExpr>hasAnyArgumentMatcher<Expr> InnerMatcher
 
Matches any argument of a call expression or a constructor call
 expression.
@@ -2871,6 +2895,17 @@ Usable as: Matcher<Expr>hasTypeMatcher<QualType> InnerMatcher
+
Matches if the expression's or declaration's type matches a type
+matcher.
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+            and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+

+
+
 Matcher<Expr>ignoringImpCastsMatcher<Expr> InnerMatcher
 
Matches expressions that match InnerMatcher after any implicit casts
 are stripped off.
@@ -3318,11 +3353,36 @@ Usable as: Matcher<QualType>pointsToMatcher<QualType> InnerMatcher
+
Matches if the matched type is a pointer type and the pointee type
+matches the specified matcher.
+
+Example matches y->x()
+    (matcher = callExpr(on(hasType(pointsTo(recordDecl(hasName("Y")))))))
+  class Y { public: void x(); };
+  void z() { Y *y; y->x(); }
+

+
+
 Matcher<QualType>referencesMatcher<Decl> InnerMatcher
 
Overloaded to match the referenced type's declaration.
 

 
 
+Matcher<QualType>referencesMatcher<QualType> InnerMatcher
+
Matches if the matched type is a reference type and the referenced
+type matches the specified matcher.
+
+Example matches X &x and const X &y
+    (matcher = varDecl(hasType(references(recordDecl(hasName("X"))))))
+  class X {
+    void a(X b) {
+      X &x = b;
+      const X &y = b;
+  };
+

+
+
 Matcher<RecordType>hasDeclarationMatcher<Decl>  InnerMatcher
 
Matches a node if the declaration associated with that node
 matches the given matcher.
@@ -3662,6 +3722,17 @@ Usable as: Matcher<ValueDecl>hasTypeMatcher<QualType> InnerMatcher
+
Matches if the expression's or declaration's type matches a type
+matcher.
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+            and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+

+
+
 Matcher<VarDecl>hasInitializerMatcher<Expr> InnerMatcher
 
Matches a variable declaration that has an initializer expression
 that matches the given matcher.
diff --git a/clang/docs/tools/dump_ast_matchers.py b/clang/docs/tools/dump_ast_matchers.py
index 7f8751ea654d..c04df8573a50 100644
--- a/clang/docs/tools/dump_ast_matchers.py
+++ b/clang/docs/tools/dump_ast_matchers.py
@@ -119,9 +119,9 @@ def add_matcher(result_type, name, args, comment, is_dyncast=False):
   # arguments.
   elif ('Matcher<' not in args or
         name in ['allOf', 'anyOf', 'anything', 'unless']):
-    narrowing_matchers[result_type + name] = matcher_html
+    narrowing_matchers[result_type + name + esc(args)] = matcher_html
   else:
-    traversal_matchers[result_type + name] = matcher_html
+    traversal_matchers[result_type + name + esc(args)] = matcher_html
 
 def act_on_decl(declaration, comment, allowed_types):
   """Parse the matcher out of the given declaration and comment.