[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?

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 &&