[ASTMatchers] [NFC] Fix code examples

[MaskRay]

More

[lebedev.ri]

Don't forget that you also need to regenerate the HTML docs:

$ cd docs/tools # yes, cd
$ ./dump_ast_matchers.py

[MaskRay]

More

[MaskRay]

More

[aaron.ballman]

The documentation needs to be regenerated for this patch. One thing that seems to be inconsistent is with the "what gets matched" messages is that sometimes it includes extra adornments like curly braces and other times it does not. It might be good to pick a style and try to be more consistent with it.

include/clang/ASTMatchers/ASTMatchers.h

1792

I don't think this adds clarity.

1841

I don't think this adds clarity.

1851

I think this adds confusion.

[MaskRay]

Revert some changes to address comments

[MaskRay]

In D42213#981700, @aaron.ballman wrote:

The documentation needs to be regenerated for this patch. One thing that seems to be inconsistent is with the "what gets matched" messages is that sometimes it includes extra adornments like curly braces and other times it does not. It might be good to pick a style and try to be more consistent with it.

Do I need to do anything to re-generate the doc and check it into this revision? If so, can you show me the Doxygen generation instruction?

Reverted some changes as they may cause confusion which are pointed by you.

[aaron.ballman]

In D42213#982047, @MaskRay wrote:

In D42213#981700, @aaron.ballman wrote:

The documentation needs to be regenerated for this patch. One thing that seems to be inconsistent is with the "what gets matched" messages is that sometimes it includes extra adornments like curly braces and other times it does not. It might be good to pick a style and try to be more consistent with it.

Do I need to do anything to re-generate the doc and check it into this revision? If so, can you show me the Doxygen generation instruction?

Yes, the documentation for this is something that has to be generated manually. You should just have to execute clang/docs/tools/dump_ast_matchers.py to regenerate the documentation.

Reverted some changes as they may cause confusion which are pointed by you.

Thanks! I found one more minor nit with some example code, but this basically looks good aside from the documentation bit.

include/clang/ASTMatchers/ASTMatchers.h

803

Spurious semi-colon in the declaration.

[MaskRay]

Address comment

[MaskRay]

I am also not sure about this function: line 3548

/// \brief Matches \c FunctionDecls and \c FunctionProtoTypes that have a
/// specific parameter count.
///
/// Given
/// \code
///   void f(int i) {}
///   void g(int i, int j) {}
///   void h(int i, int j);
///   void j(int i);
///   void k(int x, int y, int z, ...);
/// \endcode
/// functionDecl(parameterCountIs(2))
///   matches void g(int i, int j) {}
/// functionProtoType(parameterCountIs(2))
///   matches void h(int i, int j)
/// functionProtoType(parameterCountIs(3))
///   matches void k(int x, int y, int z, ...);
AST_POLYMORPHIC_MATCHER_P(parameterCountIs,
                          AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                          FunctionProtoType),
}

Both functionDecl and functionProtoType match these functions as long as the parameter count is matched.

% echo 'match functionDecl()'|clang-query =(printf 'void f(){}') -- -xc++
% echo 'match functionProtoType()'|clang-query =(printf 'void f(){}') -- -xc++

[aaron.ballman]

In D42213#982256, @MaskRay wrote:

I am also not sure about this function: line 3548

/// \brief Matches \c FunctionDecls and \c FunctionProtoTypes that have a
/// specific parameter count.
///
/// Given
/// \code
///   void f(int i) {}
///   void g(int i, int j) {}
///   void h(int i, int j);
///   void j(int i);
///   void k(int x, int y, int z, ...);
/// \endcode
/// functionDecl(parameterCountIs(2))
///   matches void g(int i, int j) {}
/// functionProtoType(parameterCountIs(2))
///   matches void h(int i, int j)
/// functionProtoType(parameterCountIs(3))
///   matches void k(int x, int y, int z, ...);
AST_POLYMORPHIC_MATCHER_P(parameterCountIs,
                          AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                          FunctionProtoType),
}

Both functionDecl and functionProtoType match these functions as long as the parameter count is matched.

% echo 'match functionDecl()'|clang-query =(printf 'void f(){}') -- -xc++
% echo 'match functionProtoType()'|clang-query =(printf 'void f(){}') -- -xc++

I'm not certain I'm following along. The quoted matcher is for parameterCountIs(), but the test code you've posted doesn't use that matcher. However, the quoted comment seems like it's wrong: functionDecl(parameterCountIs(2)) should match both g() and h(), not just g(), I believe.

[MaskRay]

In D42213#982261, @aaron.ballman wrote:

In D42213#982256, @MaskRay wrote:

I am also not sure about this function: line 3548

/// \brief Matches \c FunctionDecls and \c FunctionProtoTypes that have a
/// specific parameter count.
///
/// Given
/// \code
///   void f(int i) {}
///   void g(int i, int j) {}
///   void h(int i, int j);
///   void j(int i);
///   void k(int x, int y, int z, ...);
/// \endcode
/// functionDecl(parameterCountIs(2))
///   matches void g(int i, int j) {}
/// functionProtoType(parameterCountIs(2))
///   matches void h(int i, int j)
/// functionProtoType(parameterCountIs(3))
///   matches void k(int x, int y, int z, ...);
AST_POLYMORPHIC_MATCHER_P(parameterCountIs,
                          AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                          FunctionProtoType),
}

Both functionDecl and functionProtoType match these functions as long as the parameter count is matched.

% echo 'match functionDecl()'|clang-query =(printf 'void f(){}') -- -xc++
% echo 'match functionProtoType()'|clang-query =(printf 'void f(){}') -- -xc++

I'm not certain I'm following along. The quoted matcher is for parameterCountIs(), but the test code you've posted doesn't use that matcher. However, the quoted comment seems like it's wrong: functionDecl(parameterCountIs(2)) should match both g() and h(), not just g(), I believe.

Yes, I was asking about this because the results seemed to be wrong. I should have used parameterCountIs() to reduce the confusion :) I'll leave them untouched.

[aaron.ballman]

In D42213#982385, @MaskRay wrote:

Yes, I was asking about this because the results seemed to be wrong. I should have used parameterCountIs() to reduce the confusion :) I'll leave them untouched.

Alternatively, you can try out those declarations and the given matchers in clang-query to see if the results match what's listed, and update the comments based on what you find. Either way is fine.

[MaskRay]

functionProtoType

[aaron.ballman]

Great, all that remains is for you to regenerate the documentation file and upload that with the next patch.

[MaskRay]

Regenerate HTML docs

$ cd docs/tools # yes, cd
$ ./dump_ast_matchers.py

[aaron.ballman]

LGTM, thank you! Do you need me to commit on your behalf?

docs/LibASTMatchersReference.html

 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('caseStmt0')"><a name="caseStmt0Anchor">caseStmt</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CaseStmt.html">CaseStmt</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="caseStmt0"><pre>Matches case statements inside switch statements.
 
 Given
   switch(a) { case 42: break; default: break; }
 caseStmt()
-  matches 'case 42: break;'.
+  matches 'case 42:'.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('castExpr0')"><a name="castExpr0Anchor">castExpr</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CastExpr.html">CastExpr</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="castExpr0"><pre>Matches any cast nodes of Clang's AST.
 
 Example: castExpr() matches each of the following:
   (int) 3;
Example match: {1}, (1, 2)
   int array[4] = {1};
   vector int myvec = (vector int)(1, 2);
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('compoundStmt0')"><a name="compoundStmt0Anchor">compoundStmt</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">CompoundStmt</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="compoundStmt0"><pre>Matches compound statements.
 
-Example matches '{}' and '{{}}'in 'for (;;) {{}}'
+Example matches '{}' and '{{}}' in 'for (;;) {{}}'
   for (;;) {{}}
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('conditionalOperator0')"><a name="conditionalOperator0Anchor">conditionalOperator</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1ConditionalOperator.html">ConditionalOperator</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="conditionalOperator0"><pre>Matches conditional operator expressions.
 
 Example matches a ? b : c

 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('defaultStmt0')"><a name="defaultStmt0Anchor">defaultStmt</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1DefaultStmt.html">DefaultStmt</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="defaultStmt0"><pre>Matches default statements inside switch statements.
 
 Given
   switch(a) { case 42: break; default: break; }
 defaultStmt()
-  matches 'default: break;'.
+  matches 'default:'.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('designatedInitExpr0')"><a name="designatedInitExpr0Anchor">designatedInitExpr</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1DesignatedInitExpr.html">DesignatedInitExpr</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="designatedInitExpr0"><pre>Matches C99 designated initializer expressions [C99 6.7.8].
 
 Example: Matches { [2].y = 1.0, [0].x = 1.0 }
   point ptarray[10] = { [2].y = 1.0, [0].x = 1.0 };

 
 Example: Given
   struct T {void func();};
   T f();
   void g(T);
 materializeTemporaryExpr() matches 'f()' in these statements
   T u(f());
   g(f());
+  f().func();
 but does not match
   f();
-  f().func();
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('memberExpr0')"><a name="memberExpr0Anchor">memberExpr</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="memberExpr0"><pre>Matches member expressions.
 
 Given
   class Y {

 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('switchCase0')"><a name="switchCase0Anchor">switchCase</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1SwitchCase.html">SwitchCase</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="switchCase0"><pre>Matches case and default statements inside switch statements.
 
 Given
   switch(a) { case 42: break; default: break; }
 switchCase()
-  matches 'case 42: break;' and 'default: break;'.
+  matches 'case 42:' and 'default:'.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('switchStmt0')"><a name="switchStmt0Anchor">switchStmt</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1SwitchStmt.html">SwitchStmt</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="switchStmt0"><pre>Matches switch statements.
 
 Given
   switch(a) { case 42: break; default: break; }

 
 Given
   void f(int i) {}
   void g(int i, int j) {}
   void h(int i, int j);
   void j(int i);
   void k(int x, int y, int z, ...);
 functionDecl(parameterCountIs(2))
-  matches void g(int i, int j) {}
+  matches g and h
 functionProtoType(parameterCountIs(2))
-  matches void h(int i, int j)
+  matches g and h
 functionProtoType(parameterCountIs(3))
-  matches void k(int x, int y, int z, ...);
+  matches k
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionProtoType.html">FunctionProtoType</a>&gt;</td><td class="name" onclick="toggle('hasDynamicExceptionSpec1')"><a name="hasDynamicExceptionSpec1Anchor">hasDynamicExceptionSpec</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasDynamicExceptionSpec1"><pre>Matches functions that have a dynamic exception specification.
 
 Given:
   void f();

 
 Given
   void f(int i) {}
   void g(int i, int j) {}
   void h(int i, int j);
   void j(int i);
   void k(int x, int y, int z, ...);
 functionDecl(parameterCountIs(2))
-  matches void g(int i, int j) {}
+  matches g and h
 functionProtoType(parameterCountIs(2))
-  matches void h(int i, int j)
+  matches g and h
 functionProtoType(parameterCountIs(3))
-  matches void k(int x, int y, int z, ...);
+  matches k
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;</td><td class="name" onclick="toggle('equals6')"><a name="equals6Anchor">equals</a></td><td>bool Value</td></tr>
 <tr><td colspan="4" class="doc" id="equals6"><pre></pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;</td><td class="name" onclick="toggle('equals0')"><a name="equals0Anchor">equals</a></td><td>const ValueT  Value</td></tr>

 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>&gt;</td><td class="name" onclick="toggle('equalsIntegralValue0')"><a name="equalsIntegralValue0Anchor">equalsIntegralValue</a></td><td>std::string Value</td></tr>
 <tr><td colspan="4" class="doc" id="equalsIntegralValue0"><pre>Matches a TemplateArgument of integral type with a given value.
 
 Note that 'Value' is a string as the template argument's value is
 an arbitrary precision integer. 'Value' must be euqal to the canonical
 representation of that integral value in base 10.
 
 Given
-  template&lt;int T&gt; struct A {};
+  template&lt;int T&gt; struct C {};
   C&lt;42&gt; c;
 classTemplateSpecializationDecl(
   hasAnyTemplateArgument(equalsIntegralValue("42")))
   matches the implicit instantiation of C in C&lt;42&gt;.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>&gt;</td><td class="name" onclick="toggle('isIntegral0')"><a name="isIntegral0Anchor">isIntegral</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isIntegral0"><pre>Matches a TemplateArgument that is an integral value.
 
 Given
-  template&lt;int T&gt; struct A {};
+  template&lt;int T&gt; struct C {};
   C&lt;42&gt; c;
 classTemplateSpecializationDecl(
   hasAnyTemplateArgument(isIntegral()))
   matches the implicit instantiation of C in C&lt;42&gt;
   with isIntegral() matching 42.
 </pre></td></tr>
 
 

 Usable as: Any Matcher
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;*&gt;</td><td class="name" onclick="toggle('forEachDescendant0')"><a name="forEachDescendant0Anchor">forEachDescendant</a></td><td>Matcher&lt;*&gt;</td></tr>
 <tr><td colspan="4" class="doc" id="forEachDescendant0"><pre>Matches AST nodes that have descendant AST nodes that match the
 provided matcher.
 
-Example matches X, A, B, C
+Example matches X, A, A::X, B, B::C, B::C::X
   (matcher = cxxRecordDecl(forEachDescendant(cxxRecordDecl(hasName("X")))))
-  class X {};  Matches X, because X::X is a class of name X inside X.
-  class A { class X {}; };
+  class X {};
+  class A { class X {}; };  Matches A, because A::X is a class of name
+                            X inside A.
   class B { class C { class X {}; }; };
 
 DescendantT must be an AST base type.
 
 As opposed to 'hasDescendant', 'forEachDescendant' will cause a match for
 each result that matches instead of only on the first one.
 
 Note: Recursively combined ForEachDescendant can cause many matches:
   cxxRecordDecl(forEachDescendant(cxxRecordDecl(
     forEachDescendant(cxxRecordDecl())
   )))
 will match 10 times (plus injected class name matches) on:
   class A { class B { class C { class D { class E {}; }; }; }; };
 
 Usable as: Any Matcher
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;*&gt;</td><td class="name" onclick="toggle('forEach0')"><a name="forEach0Anchor">forEach</a></td><td>Matcher&lt;*&gt;</td></tr>
 <tr><td colspan="4" class="doc" id="forEach0"><pre>Matches AST nodes that have child AST nodes that match the
 provided matcher.
 
-Example matches X, Y
+Example matches X, Y, Y::X, Z::Y, Z::Y::X
   (matcher = cxxRecordDecl(forEach(cxxRecordDecl(hasName("X")))
-  class X {};  Matches X, because X::X is a class of name X inside X.
-  class Y { class X {}; };
+  class X {};
+  class Y { class X {}; };  Matches Y, because Y::X is a class of name X
+                            inside Y.
   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

 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>&gt;</td><td class="name" onclick="toggle('on0')"><a name="on0Anchor">on</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>&gt; InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="on0"><pre>Matches on the implicit object argument of a member call expression.
 
 Example matches y.x()
   (matcher = cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("Y"))))))
   class Y { public: void x(); };
-  void z() { Y y; y.x(); }",
+  void z() { Y y; y.x(); }
 
 FIXME: Overload to allow directly matching types?
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>&gt;</td><td class="name" onclick="toggle('thisPointerType1')"><a name="thisPointerType1Anchor">thisPointerType</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>&gt; InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="thisPointerType1"><pre>Overloaded to match the type's declaration.
 </pre></td></tr>

 <tr><td colspan="4" class="doc" id="hasTemplateArgument0"><pre>Matches classTemplateSpecializations, templateSpecializationType and
 functionDecl where the n'th TemplateArgument matches the given InnerMatcher.
 
 Given
   template&lt;typename T, typename U&gt; class A {};
   A&lt;bool, int&gt; b;
   A&lt;int, bool&gt; c;
 
-  template&lt;typename T&gt; f() {};
+  template&lt;typename T&gt; void f() {}
   void func() { f&lt;int&gt;(); };
 classTemplateSpecializationDecl(hasTemplateArgument(
     1, refersToType(asString("int"))))
   matches the specialization A&lt;bool, int&gt;
 
 functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
   matches the specialization f&lt;int&gt;
 </pre></td></tr>

 <tr><td colspan="4" class="doc" id="hasTemplateArgument2"><pre>Matches classTemplateSpecializations, templateSpecializationType and
 functionDecl where the n'th TemplateArgument matches the given InnerMatcher.
 
 Given
   template&lt;typename T, typename U&gt; class A {};
   A&lt;bool, int&gt; b;
   A&lt;int, bool&gt; c;
 
-  template&lt;typename T&gt; f() {};
+  template&lt;typename T&gt; void f() {}
   void func() { f&lt;int&gt;(); };
 classTemplateSpecializationDecl(hasTemplateArgument(
     1, refersToType(asString("int"))))
   matches the specialization A&lt;bool, int&gt;
 
 functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
   matches the specialization f&lt;int&gt;
 </pre></td></tr>
Usable as: Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>&gt;,
   Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>&gt;
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>&gt;</td><td class="name" onclick="toggle('isExpr0')"><a name="isExpr0Anchor">isExpr</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>&gt; InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="isExpr0"><pre>Matches a sugar TemplateArgument that refers to a certain expression.
 
 Given
-  template&lt;typename T&gt; struct A {};
-  struct B { B* next; };
+  struct B { int next; };
+  template&lt;int(B::*next_ptr)&gt; struct A {};
   A&lt;&amp;B::next&gt; a;
 templateSpecializationType(hasAnyTemplateArgument(
   isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next"))))))))
   matches the specialization A&lt;&amp;B::next&gt; with fieldDecl(...) matching
     B::next
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>&gt;</td><td class="name" onclick="toggle('refersToDeclaration0')"><a name="refersToDeclaration0Anchor">refersToDeclaration</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>&gt; InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="refersToDeclaration0"><pre>Matches a canonical TemplateArgument that refers to a certain
 declaration.
 
 Given
-  template&lt;typename T&gt; struct A {};
-  struct B { B* next; };
+  struct B { int next; };
+  template&lt;int(B::*next_ptr)&gt; struct A {};
   A&lt;&amp;B::next&gt; a;
 classTemplateSpecializationDecl(hasAnyTemplateArgument(
-    refersToDeclaration(fieldDecl(hasName("next"))))
+    refersToDeclaration(fieldDecl(hasName("next")))))
   matches the specialization A&lt;&amp;B::next&gt; with fieldDecl(...) matching
     B::next
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>&gt;</td><td class="name" onclick="toggle('refersToIntegralType0')"><a name="refersToIntegralType0Anchor">refersToIntegralType</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>&gt; InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="refersToIntegralType0"><pre>Matches a TemplateArgument that referes to an integral type.
 
 Given
-  template&lt;int T&gt; struct A {};
+  template&lt;int T&gt; struct C {};
   C&lt;42&gt; c;
 classTemplateSpecializationDecl(
   hasAnyTemplateArgument(refersToIntegralType(asString("int"))))
   matches the implicit instantiation of C in C&lt;42&gt;.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>&gt;</td><td class="name" onclick="toggle('refersToTemplate0')"><a name="refersToTemplate0Anchor">refersToTemplate</a></td><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateName.html">TemplateName</a>&gt; InnerMatcher</td></tr>

 <tr><td colspan="4" class="doc" id="hasTemplateArgument1"><pre>Matches classTemplateSpecializations, templateSpecializationType and
 functionDecl where the n'th TemplateArgument matches the given InnerMatcher.
 
 Given
   template&lt;typename T, typename U&gt; class A {};
   A&lt;bool, int&gt; b;
   A&lt;int, bool&gt; c;
 
-  template&lt;typename T&gt; f() {};
+  template&lt;typename T&gt; void f() {}
   void func() { f&lt;int&gt;(); };
 classTemplateSpecializationDecl(hasTemplateArgument(
     1, refersToType(asString("int"))))
   matches the specialization A&lt;bool, int&gt;
 
 functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
   matches the specialization f&lt;int&gt;
 </pre></td></tr>

include/clang/ASTMatchers/ASTMatchers.h

 /// functionDecl where the n'th TemplateArgument matches the given InnerMatcher.
 ///
 /// Given
 /// \code
 ///   template<typename T, typename U> class A {};
 ///   A<bool, int> b;
 ///   A<int, bool> c;
 ///
-///   template<typename T> f() {};
+///   template<typename T> void f() {}
 ///   void func() { f<int>(); };
 /// \endcode
 /// classTemplateSpecializationDecl(hasTemplateArgument(
 ///     1, refersToType(asString("int"))))
 ///   matches the specialization \c A<bool, int>
 ///
 /// functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
 ///   matches the specialization \c f<int>
AST_MATCHER_P(TemplateArgument, refersToTemplate,
   return InnerMatcher.matches(Node.getAsTemplate(), Finder, Builder);
 }
 
 /// \brief Matches a canonical TemplateArgument that refers to a certain
 /// declaration.
 ///
 /// Given
 /// \code
-///   template<typename T> struct A {};
-///   struct B { B* next; };
+///   struct B { int next; };
+///   template<int(B::*next_ptr)> struct A {};
 ///   A<&B::next> a;
 /// \endcode
 /// classTemplateSpecializationDecl(hasAnyTemplateArgument(
-///     refersToDeclaration(fieldDecl(hasName("next"))))
+///     refersToDeclaration(fieldDecl(hasName("next")))))
 ///   matches the specialization \c A<&B::next> with \c fieldDecl(...) matching
 ///     \c B::next
 AST_MATCHER_P(TemplateArgument, refersToDeclaration,
               internal::Matcher<Decl>, InnerMatcher) {
   if (Node.getKind() == TemplateArgument::Declaration)
     return InnerMatcher.matches(*Node.getAsDecl(), Finder, Builder);
   return false;
 }
 
 /// \brief Matches a sugar TemplateArgument that refers to a certain expression.
 ///
 /// Given
 /// \code
-///   template<typename T> struct A {};
-///   struct B { B* next; };
+///   struct B { int next; };
+///   template<int(B::*next_ptr)> struct A {};
 ///   A<&B::next> a;
 /// \endcode
 /// templateSpecializationType(hasAnyTemplateArgument(
 ///   isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next"))))))))
 ///   matches the specialization \c A<&B::next> with \c fieldDecl(...) matching
 ///     \c B::next
 AST_MATCHER_P(TemplateArgument, isExpr, internal::Matcher<Expr>, InnerMatcher) {
   if (Node.getKind() == TemplateArgument::Expression)
     return InnerMatcher.matches(*Node.getAsExpr(), Finder, Builder);
   return false;
 }
 
 /// \brief Matches a TemplateArgument that is an integral value.
 ///
 /// Given
 /// \code
-///   template<int T> struct A {};
+///   template<int T> struct C {};
 ///   C<42> c;
 /// \endcode
 /// classTemplateSpecializationDecl(
 ///   hasAnyTemplateArgument(isIntegral()))
 ///   matches the implicit instantiation of C in C<42>
 ///   with isIntegral() matching 42.
 AST_MATCHER(TemplateArgument, isIntegral) {
   return Node.getKind() == TemplateArgument::Integral;
 }
 
 /// \brief Matches a TemplateArgument that referes to an integral type.
 ///
 /// Given
 /// \code
-///   template<int T> struct A {};
+///   template<int T> struct C {};
 ///   C<42> c;
 /// \endcode
 /// classTemplateSpecializationDecl(
 ///   hasAnyTemplateArgument(refersToIntegralType(asString("int"))))
 ///   matches the implicit instantiation of C in C<42>.
 AST_MATCHER_P(TemplateArgument, refersToIntegralType,
               internal::Matcher<QualType>, InnerMatcher) {
   if (Node.getKind() != TemplateArgument::Integral)
     return false;
   return InnerMatcher.matches(Node.getIntegralType(), Finder, Builder);
 }
 
 /// \brief Matches a TemplateArgument of integral type with a given value.
 ///
 /// Note that 'Value' is a string as the template argument's value is
 /// an arbitrary precision integer. 'Value' must be euqal to the canonical
 /// representation of that integral value in base 10.
 ///
 /// Given
 /// \code
-///   template<int T> struct A {};
+///   template<int T> struct C {};
 ///   C<42> c;
 /// \endcode
 /// classTemplateSpecializationDecl(
 ///   hasAnyTemplateArgument(equalsIntegralValue("42")))
 ///   matches the implicit instantiation of C in C<42>.
 AST_MATCHER_P(TemplateArgument, equalsIntegralValue,
               std::string, Value) {
   if (Node.getKind() != TemplateArgument::Integral)

 ///   struct T {void func();};
 ///   T f();
 ///   void g(T);
 /// \endcode
 /// materializeTemporaryExpr() matches 'f()' in these statements
 /// \code
 ///   T u(f());
 ///   g(f());
+///   f().func();
 /// \endcode
 /// but does not match
 /// \code
 ///   f();
-///   f().func();
 /// \endcode
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
                                                    MaterializeTemporaryExpr>
     materializeTemporaryExpr;
 
 /// \brief Matches new expressions.
 ///
 /// Given

 
 /// \brief Matches switch statements.
 ///
 /// Given
 /// \code
 ///   switch(a) { case 42: break; default: break; }
 /// \endcode
 /// switchStmt()
 ///   matches 'switch(a)'.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, SwitchStmt> switchStmt;
 
 /// \brief Matches case and default statements inside switch statements.
 ///
 /// Given
 /// \code
 ///   switch(a) { case 42: break; default: break; }
 /// \endcode
 /// switchCase()
-///   matches 'case 42: break;' and 'default: break;'.
+///   matches 'case 42:' and 'default:'.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, SwitchCase> switchCase;
 
 /// \brief Matches case statements inside switch statements.
 ///
 /// Given
 /// \code
 ///   switch(a) { case 42: break; default: break; }
 /// \endcode
 /// caseStmt()
-///   matches 'case 42: break;'.
+///   matches 'case 42:'.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CaseStmt> caseStmt;
 
 /// \brief Matches default statements inside switch statements.
 ///
 /// Given
 /// \code
 ///   switch(a) { case 42: break; default: break; }
 /// \endcode
 /// defaultStmt()
-///   matches 'default: break;'.
+///   matches 'default:'.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, DefaultStmt>
     defaultStmt;
 
 /// \brief Matches compound statements.
 ///
-/// Example matches '{}' and '{{}}'in 'for (;;) {{}}'
+/// Example matches '{}' and '{{}}' in 'for (;;) {{}}'
 /// \code
 ///   for (;;) {{}}
 /// \endcode
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CompoundStmt>
     compoundStmt;
 
 /// \brief Matches catch statements.
 ///
 /// \code
 ///   try {} catch(int i) {}
 /// \endcode
 /// cxxCatchStmt()
 ///   matches 'catch(int i)'
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXCatchStmt>
     cxxCatchStmt;
 
 /// \brief Matches try statements.
 ///
 /// \code
 ///   try {} catch(int i) {}
 /// \endcode
 /// cxxTryStmt()
 ///   matches 'try {}'
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXTryStmt> cxxTryStmt;
 
 /// \brief Matches throw expressions.
 ///
 /// \code
 ///   try { throw 5; } catch(int i) {}
 /// \endcode
 /// cxxThrowExpr()

 /// Usable as: Any Matcher
 extern const internal::ArgumentAdaptingMatcherFunc<
     internal::HasDescendantMatcher>
     hasDescendant;
 
 /// \brief Matches AST nodes that have child AST nodes that match the
 /// provided matcher.
 ///
-/// Example matches X, Y
+/// Example matches X, Y, Y::X, Z::Y, Z::Y::X
 ///   (matcher = cxxRecordDecl(forEach(cxxRecordDecl(hasName("X")))
 /// \code
-///   class X {};  // Matches X, because X::X is a class of name X inside X.
-///   class Y { class X {}; };
+///   class X {};
+///   class Y { class X {}; };  // Matches Y, because Y::X is a class of name X
+///                             // inside Y.
 ///   class Z { class Y { class X {}; }; };  // Does not match Z.
 /// \endcode
 ///
 /// 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
 extern const internal::ArgumentAdaptingMatcherFunc<internal::ForEachMatcher>
     forEach;
 
 /// \brief Matches AST nodes that have descendant AST nodes that match the
 /// provided matcher.
 ///
-/// Example matches X, A, B, C
+/// Example matches X, A, A::X, B, B::C, B::C::X
 ///   (matcher = cxxRecordDecl(forEachDescendant(cxxRecordDecl(hasName("X")))))
 /// \code
-///   class X {};  // Matches X, because X::X is a class of name X inside X.
-///   class A { class X {}; };
+///   class X {};
+///   class A { class X {}; };  // Matches A, because A::X is a class of name
+///                             // X inside A.
 ///   class B { class C { class X {}; }; };
 /// \endcode
 ///
 /// DescendantT must be an AST base type.
 ///
 /// As opposed to 'hasDescendant', 'forEachDescendant' will cause a match for
 /// each result that matches instead of only on the first one.
 ///

 }
 
 /// \brief Matches on the implicit object argument of a member call expression.
 ///
 /// Example matches y.x()
 ///   (matcher = cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("Y"))))))
 /// \code
 ///   class Y { public: void x(); };
-///   void z() { Y y; y.x(); }",
+///   void z() { Y y; y.x(); }
 /// \endcode
 ///
 /// FIXME: Overload to allow directly matching types?
 AST_MATCHER_P(CXXMemberCallExpr, on, internal::Matcher<Expr>,
               InnerMatcher) {
   const Expr *ExprNode = Node.getImplicitObjectArgument()
                             ->IgnoreParenImpCasts();
   return (ExprNode != nullptr &&

 /// \code
 ///   void f(int i) {}
 ///   void g(int i, int j) {}
 ///   void h(int i, int j);
 ///   void j(int i);
 ///   void k(int x, int y, int z, ...);
 /// \endcode
 /// functionDecl(parameterCountIs(2))
-///   matches void g(int i, int j) {}
+///   matches \c g and \c h
 /// functionProtoType(parameterCountIs(2))
-///   matches void h(int i, int j)
+///   matches \c g and \c h
 /// functionProtoType(parameterCountIs(3))
-///   matches void k(int x, int y, int z, ...);
+///   matches \c k
 AST_POLYMORPHIC_MATCHER_P(parameterCountIs,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                           FunctionProtoType),
                           unsigned, N) {
   return Node.getNumParams() == N;
 }
 
 /// \brief Matches \c FunctionDecls that have a noreturn attribute.