[llvm-branch-commits] [clang] [clang][test] add testing for the AST matcher reference (PR #94248)

Julian Schmidt via llvm-branch-commits llvm-branch-commits at lists.llvm.org
Tue Jun 4 08:58:48 PDT 2024


https://github.com/5chmidti updated https://github.com/llvm/llvm-project/pull/94248

>From 2e90b54e4d8dbe6ff295c24938641882bee9747e Mon Sep 17 00:00:00 2001
From: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: Sat, 1 Jun 2024 18:40:03 +0200
Subject: [PATCH 1/4] [clang][test] add testing for the AST matcher reference

Previously, the examples in the AST matcher reference, which gets
generated by the doxygen comments in `ASTMatchers.h`, were untested
and best effort.
Some of the matchers had no or wrong examples of how to use the matcher.

This patch introduces a simple DSL around doxygen commands to enable
testing the AST matcher documentation in a way that should be relatively
easy.
In `ASTMatchers.h`, most matchers are documented with a doxygen comment.
Most of these also have a code example that aims to show what the
matcher will match, given a matcher somewhere in the documentation text.
The way that testing the documentation is done, is by using doxygens
alias feature to declare custom aliases. These aliases forward to
`<tt>text</tt>` (which is what doxygens \c does, but for multiple words).
Using the doxygen aliases was the obvious choice, because there are
(now) four consumers:
 - people reading the header/using signature help
 - the doxygen generated documentation
 - the generated html AST matcher reference
 - (new) the generated matcher tests

This patch rewrites/extends the documentation such that all matchers
have a documented example.
The new `generate_ast_matcher_doc_tests.py` script will warn on any
undocumented matchers (but not on matchers without a doxygen comment)
and provides diagnostics and statistics about the matchers.
Below is a file-level comment from the test generation script that
describes how documenting matchers to be tested works on a slightly more
technical level. In general, the new comments can be used as a reference
for how to implement a tested documentation.

The current statistics emitted by the parser are:

```text
Statistics:
        doxygen_blocks                :   519
        missing_tests                 :    10
        skipped_objc                  :    42
        code_snippets                 :   503
        matches                       :   820
        matchers                      :   580
        tested_matchers               :   574
        none_type_matchers            :     6
```

The tests are generated during building and the script will only print
something if it found an issue (compile failure, parsing issues,
the expected and actual number of failures differs).

DSL for generating the tests from documentation.

TLDR:
The order for a single code snippet example is:

  \header{a.h}
  \endheader     <- zero or more header

  \code
    int a = 42;
  \endcode
  \compile_args{-std=c++,c23-or-later} <- optional, supports std ranges and
                                          whole languages

  \matcher{expr()} <- one or more matchers in succession
  \match{42}   <- one ore more matches in succession

  \matcher{varDecl()} <- new matcher resets the context, the above
                         \match will not count for this new
                         matcher(-group)
  \match{int a  = 42} <- only applies to the previous matcher (no the
                         previous case)

The above block can be repeated inside of a doxygen command for multiple
code examples.

Language Grammar:
  [] denotes an optional, and <> denotes user-input

  compile_args j:= \compile_args{[<compile_arg>;]<compile_arg>}
  matcher_tag_key ::= type
  match_tag_key ::= type || std || count
  matcher_tags ::= [matcher_tag_key=<value>;]matcher_tag_key=<value>
  match_tags ::= [match_tag_key=<value>;]match_tag_key=<value>
  matcher ::= \matcher{[matcher_tags$]<matcher>}
  matchers ::= [matcher] matcher
  match ::= \match{[match_tags$]<match>}
  matches ::= [match] match
  case ::= matchers matches
  cases ::= [case] case
  header-block ::= \header{<name>} <code> \endheader
  code-block ::= \code <code> \endcode
  testcase ::= code-block [compile_args] cases

The 'std' tag and '\compile_args' support specifying a specific
language version, a whole language and all of it's versions, and thresholds
(implies ranges). Multiple arguments are passed with a ',' seperator.
For a language and version to execute a tested matcher, it has to match
the specified '\compile_args' for the code, and the 'std' tag for the matcher.
Predicates for the 'std' compiler flag are used with disjunction between
languages (e.g. 'c || c++') and conjunction for all predicates specific
to each language (e.g. 'c++11-or-later && c++23-or-earlier').

Examples:
 - c                                    all available versions of C
 - c++11                                only C++11
 - c++11-or-later                       C++11 or later
 - c++11-or-earlier                     C++11 or earlier
 - c++11-or-later,c++23-or-earlier,c    all of C and C++ between 11 and
                                          23 (inclusive)
 - c++11-23,c                             same as above

Tags:

  Type:
  Match types are used to select where the string that is used to check if
  a node matches comes from.
  Available: code, name, typestr, typeofstr.
  The default is 'code'.

  Matcher types are used to mark matchers as submatchers with 'sub' or as
  deactivated using 'none'. Testing submatchers is not implemented.

  Count:
  Specifying a 'count=n' on a match will result in a test that requires that
  the specified match will be matched n times. Default is 1.

  Std:
  A match allows specifying if it matches only in specific language versions.
  This may be needed when the AST differs between language versions.

Fixes #57607
Fixes #63748
---
 clang/docs/LibASTMatchersReference.html       | 7951 ++++++++++++-----
 clang/docs/ReleaseNotes.rst                   |    2 +
 clang/docs/doxygen.cfg.in                     |    9 +-
 clang/docs/tools/dump_ast_matchers.py         |   68 +-
 clang/include/clang/ASTMatchers/ASTMatchers.h | 5525 ++++++++----
 clang/unittests/ASTMatchers/ASTMatchersTest.h |  446 +-
 clang/unittests/ASTMatchers/CMakeLists.txt    |   15 +
 clang/utils/generate_ast_matcher_doc_tests.py | 1160 +++
 8 files changed, 11263 insertions(+), 3913 deletions(-)
 create mode 100755 clang/utils/generate_ast_matcher_doc_tests.py

diff --git a/clang/docs/LibASTMatchersReference.html b/clang/docs/LibASTMatchersReference.html
index a16b9c44ef0ea..baf39befd796a 100644
--- a/clang/docs/LibASTMatchersReference.html
+++ b/clang/docs/LibASTMatchersReference.html
@@ -586,28 +586,36 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
   #pragma omp declare simd
   int min();
-attr()
-  matches "nodiscard", "nonnull", "noinline", and the whole "#pragma" line.
+
+The matcher attr()
+matches nodiscard, nonnull, noinline, and
+declare simd.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>></td><td class="name" onclick="toggle('cxxBaseSpecifier0')"><a name="cxxBaseSpecifier0Anchor">cxxBaseSpecifier</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxBaseSpecifier0"><pre>Matches class bases.
 
-Examples matches public virtual B.
+Given
   class B {};
   class C : public virtual B {};
+
+The matcher cxxRecordDecl(hasDirectBase(cxxBaseSpecifier()))
+matches C.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>></td><td class="name" onclick="toggle('cxxCtorInitializer0')"><a name="cxxCtorInitializer0Anchor">cxxCtorInitializer</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxCtorInitializer0"><pre>Matches constructor initializers.
 
-Examples matches i(42).
+Given
   class C {
     C() : i(42) {}
     int i;
   };
+
+The matcher cxxCtorInitializer()
+matches i(42).
 </pre></td></tr>
 
 
@@ -619,17 +627,22 @@ <h2 id="decl-matchers">Node Matchers</h2>
   public:
     int a;
   };
-accessSpecDecl()
-  matches 'public:'
+
+The matcher accessSpecDecl()
+matches public:.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('bindingDecl0')"><a name="bindingDecl0Anchor">bindingDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BindingDecl.html">BindingDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="bindingDecl0"><pre>Matches binding declarations
-Example matches foo and bar
-(matcher = bindingDecl()
 
-  auto [foo, bar] = std::make_pair{42, 42};
+Given
+  struct pair { int x; int y; };
+  pair make(int, int);
+  auto [foo, bar] = make(42, 42);
+
+The matcher bindingDecl()
+matches foo and bar.
 </pre></td></tr>
 
 
@@ -642,14 +655,18 @@ <h2 id="decl-matchers">Node Matchers</h2>
   myFunc(^(int p) {
     printf("%d", p);
   })
+
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('classTemplateDecl0')"><a name="classTemplateDecl0Anchor">classTemplateDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ClassTemplateDecl.html">ClassTemplateDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="classTemplateDecl0"><pre>Matches C++ class template declarations.
 
-Example matches Z
+Given
   template<class T> class Z {};
+
+The matcher classTemplateDecl()
+matches Z.
 </pre></td></tr>
 
 
@@ -660,13 +677,14 @@ <h2 id="decl-matchers">Node Matchers</h2>
   template<class T1, class T2, int I>
   class A {};
 
-  template<class T, int I>
-  class A<T, T*, I> {};
+  template<class T, int I> class A<T, T*, I> {};
 
   template<>
   class A<int, int, 1> {};
-classTemplatePartialSpecializationDecl()
-  matches the specialization A<T,T*,I> but not A<int,int,1>
+
+The matcher classTemplatePartialSpecializationDecl()
+matches template<class T, int I> class A<T, T*, I> {},
+but does not match A<int, int, 1>.
 </pre></td></tr>
 
 
@@ -677,87 +695,128 @@ <h2 id="decl-matchers">Node Matchers</h2>
   template<typename T> class A {};
   template<> class A<double> {};
   A<int> a;
-classTemplateSpecializationDecl()
-  matches the specializations A<int> and A<double>
+
+The matcher classTemplateSpecializationDecl()
+matches class A<int>
+and class A<double>.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('conceptDecl0')"><a name="conceptDecl0Anchor">conceptDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ConceptDecl.html">ConceptDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="conceptDecl0"><pre>Matches concept declarations.
 
-Example matches integral
-  template<typename T>
-  concept integral = std::is_integral_v<T>;
+Given
+  template<typename T> concept my_concept = true;
+
+
+The matcher conceptDecl()
+matches template<typename T>
+concept my_concept = true.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('cxxConstructorDecl0')"><a name="cxxConstructorDecl0Anchor">cxxConstructorDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructorDecl.html">CXXConstructorDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxConstructorDecl0"><pre>Matches C++ constructor declarations.
 
-Example matches Foo::Foo() and Foo::Foo(int)
+Given
   class Foo {
    public:
     Foo();
     Foo(int);
     int DoSomething();
   };
+
+  struct Bar {};
+
+
+The matcher cxxConstructorDecl()
+matches Foo() and Foo(int).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('cxxConversionDecl0')"><a name="cxxConversionDecl0Anchor">cxxConversionDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConversionDecl.html">CXXConversionDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxConversionDecl0"><pre>Matches conversion operator declarations.
 
-Example matches the operator.
+Given
   class X { operator int() const; };
+
+
+The matcher cxxConversionDecl()
+matches operator int() const.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('cxxDeductionGuideDecl0')"><a name="cxxDeductionGuideDecl0Anchor">cxxDeductionGuideDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXDeductionGuideDecl.html">CXXDeductionGuideDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxDeductionGuideDecl0"><pre>Matches user-defined and implicitly generated deduction guide.
 
-Example matches the deduction guide.
+Given
   template<typename T>
-  class X { X(int) };
+  class X { X(int); };
   X(int) -> X<int>;
+
+
+The matcher cxxDeductionGuideDecl()
+matches the written deduction guide
+auto (int) -> X<int>,
+the implicit copy deduction guide auto (int) -> X<T>
+and the implicitly declared deduction guide
+auto (X<T>) -> X<T>.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('cxxDestructorDecl0')"><a name="cxxDestructorDecl0Anchor">cxxDestructorDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXDestructorDecl.html">CXXDestructorDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxDestructorDecl0"><pre>Matches explicit C++ destructor declarations.
 
-Example matches Foo::~Foo()
+Given
   class Foo {
    public:
     virtual ~Foo();
   };
+
+  struct Bar {};
+
+
+The matcher cxxDestructorDecl()
+matches virtual ~Foo().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('cxxMethodDecl0')"><a name="cxxMethodDecl0Anchor">cxxMethodDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxMethodDecl0"><pre>Matches method declarations.
 
-Example matches y
+Given
   class X { void y(); };
+
+
+The matcher cxxMethodDecl()
+matches void y().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('cxxRecordDecl0')"><a name="cxxRecordDecl0Anchor">cxxRecordDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxRecordDecl0"><pre>Matches C++ class declarations.
 
-Example matches X, Z
+Given
   class X;
   template<class T> class Z {};
+
+The matcher cxxRecordDecl()
+matches X and Z.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('decl0')"><a name="decl0Anchor">decl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="decl0"><pre>Matches declarations.
 
-Examples matches X, C, and the friend declaration inside C;
+Given
   void X();
   class C {
-    friend X;
+    friend void X();
   };
+
+The matcher decl()
+matches void X(), C
+and friend void X().
 </pre></td></tr>
 
 
@@ -767,40 +826,49 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   class X { int y; };
-declaratorDecl()
-  matches int y.
+
+The matcher declaratorDecl()
+matches int y.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('decompositionDecl0')"><a name="decompositionDecl0Anchor">decompositionDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DecompositionDecl.html">DecompositionDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="decompositionDecl0"><pre>Matches decomposition-declarations.
 
-Examples matches the declaration node with foo and bar, but not
-number.
-(matcher = declStmt(has(decompositionDecl())))
-
+Given
+  struct pair { int x; int y; };
+  pair make(int, int);
   int number = 42;
-  auto [foo, bar] = std::make_pair{42, 42};
+  auto [foo, bar] = make(42, 42);
+
+The matcher decompositionDecl()
+matches auto [foo, bar] = make(42, 42),
+but does not match number.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('enumConstantDecl0')"><a name="enumConstantDecl0Anchor">enumConstantDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1EnumConstantDecl.html">EnumConstantDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="enumConstantDecl0"><pre>Matches enum constants.
 
-Example matches A, B, C
+Given
   enum X {
     A, B, C
   };
+The matcher enumConstantDecl()
+matches A, B and C.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('enumDecl0')"><a name="enumDecl0Anchor">enumDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1EnumDecl.html">EnumDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="enumDecl0"><pre>Matches enum declarations.
 
-Example matches X
+Given
   enum X {
     A, B, C
   };
+
+The matcher enumDecl()
+matches the enum X.
 </pre></td></tr>
 
 
@@ -808,9 +876,14 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="fieldDecl0"><pre>Matches field declarations.
 
 Given
-  class X { int m; };
-fieldDecl()
-  matches 'm'.
+  int a;
+  struct Foo {
+    int x;
+  };
+  void bar(int val);
+
+The matcher fieldDecl()
+matches int x.
 </pre></td></tr>
 
 
@@ -819,16 +892,20 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   class X { friend void foo(); };
-friendDecl()
-  matches 'friend void foo()'.
+
+The matcher friendDecl()
+matches friend void foo().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('functionDecl0')"><a name="functionDecl0Anchor">functionDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="functionDecl0"><pre>Matches function declarations.
 
-Example matches f
+Given
   void f();
+
+The matcher functionDecl()
+matches void f().
 </pre></td></tr>
 
 
@@ -837,6 +914,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Example matches f
   template<class T> void f(T t) {}
+
+
+The matcher functionTemplateDecl()
+matches template<class T> void f(T t) {}.
 </pre></td></tr>
 
 
@@ -845,8 +926,8 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   struct X { struct { int a; }; };
-indirectFieldDecl()
-  matches 'a'.
+The matcher indirectFieldDecl()
+matches a.
 </pre></td></tr>
 
 
@@ -854,10 +935,13 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="labelDecl0"><pre>Matches a declaration of label.
 
 Given
-  goto FOO;
-  FOO: bar();
-labelDecl()
-  matches 'FOO:'
+  void bar();
+  void foo() {
+    goto FOO;
+    FOO: bar();
+  }
+The matcher labelDecl()
+matches FOO: bar().
 </pre></td></tr>
 
 
@@ -866,8 +950,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   extern "C" {}
-linkageSpecDecl()
-  matches "extern "C" {}"
+
+The matcher linkageSpecDecl()
+matches extern "C" {}.
 </pre></td></tr>
 
 
@@ -875,12 +960,18 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="namedDecl0"><pre>Matches a declaration of anything that could have a name.
 
 Example matches X, S, the anonymous union type, i, and U;
+Given
   typedef int X;
   struct S {
     union {
       int i;
     } U;
   };
+The matcher namedDecl()
+matches typedef int X, S, int i
+ and U,
+with S matching twice in C++.
+Once for the injected class name and once for the declaration itself.
 </pre></td></tr>
 
 
@@ -890,8 +981,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   namespace test {}
   namespace alias = ::test;
-namespaceAliasDecl()
-  matches "namespace alias" but not "namespace test"
+
+The matcher namespaceAliasDecl()
+matches alias,
+but does not match test.
 </pre></td></tr>
 
 
@@ -901,8 +994,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   namespace {}
   namespace test {}
-namespaceDecl()
-  matches "namespace {}" and "namespace test {}"
+
+The matcher namespaceDecl()
+matches namespace {} and namespace test {}.
 </pre></td></tr>
 
 
@@ -911,8 +1005,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   template <typename T, int N> struct C {};
-nonTypeTemplateParmDecl()
-  matches 'N', but not 'T'.
+
+The matcher nonTypeTemplateParmDecl()
+matches int N,
+but does not match typename T.
 </pre></td></tr>
 
 
@@ -922,6 +1018,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Example matches Foo (Additions)
   @interface Foo (Additions)
   @end
+
 </pre></td></tr>
 
 
@@ -931,6 +1028,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Example matches Foo (Additions)
   @implementation Foo (Additions)
   @end
+
 </pre></td></tr>
 
 
@@ -940,6 +1038,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Example matches Foo
   @implementation Foo
   @end
+
 </pre></td></tr>
 
 
@@ -949,6 +1048,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Example matches Foo
   @interface Foo
   @end
+
 </pre></td></tr>
 
 
@@ -960,6 +1060,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
     BOOL _enabled;
   }
   @end
+
 </pre></td></tr>
 
 
@@ -974,6 +1075,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
   @implementation Foo
   - (void)method {}
   @end
+
 </pre></td></tr>
 
 
@@ -984,6 +1086,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
   @interface Foo
   @property BOOL enabled;
   @end
+
 </pre></td></tr>
 
 
@@ -993,6 +1096,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Example matches FooDelegate
   @protocol FooDelegate
   @end
+
 </pre></td></tr>
 
 
@@ -1001,48 +1105,58 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   void f(int x);
-parmVarDecl()
-  matches int x.
+The matcher parmVarDecl()
+matches int x.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('recordDecl0')"><a name="recordDecl0Anchor">recordDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1RecordDecl.html">RecordDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="recordDecl0"><pre>Matches class, struct, and union declarations.
 
-Example matches X, Z, U, and S
+Given
   class X;
   template<class T> class Z {};
   struct S {};
   union U {};
+
+The matcher recordDecl()
+matches X, Z,
+S and U.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('staticAssertDecl0')"><a name="staticAssertDecl0Anchor">staticAssertDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1StaticAssertDecl.html">StaticAssertDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="staticAssertDecl0"><pre>Matches a C++ static_assert declaration.
 
-Example:
-  staticAssertDecl()
-matches
-  static_assert(sizeof(S) == sizeof(int))
-in
+Given
   struct S {
     int x;
   };
   static_assert(sizeof(S) == sizeof(int));
+
+
+The matcher staticAssertDecl()
+matches static_assert(sizeof(S) == sizeof(int)).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('tagDecl0')"><a name="tagDecl0Anchor">tagDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="tagDecl0"><pre>Matches tag declarations.
 
-Example matches X, Z, U, S, E
+Given
   class X;
   template<class T> class Z {};
   struct S {};
   union U {};
-  enum E {
-    A, B, C
-  };
+  enum E { A, B, C };
+
+
+The matcher tagDecl()
+matches class X, class Z {}, the injected class name
+class Z, struct S {},
+the injected class name struct S, union U {},
+the injected class name union U
+and enum E { A, B, C }.
 </pre></td></tr>
 
 
@@ -1051,8 +1165,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   template <template <typename> class Z, int N> struct C {};
-templateTypeParmDecl()
-  matches 'Z', but not 'N'.
+
+The matcher templateTemplateParmDecl()
+matches template <typename> class Z,
+but does not match int N.
 </pre></td></tr>
 
 
@@ -1061,8 +1177,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   template <typename T, int N> struct C {};
-templateTypeParmDecl()
-  matches 'T', but not 'N'.
+
+The matcher templateTypeParmDecl()
+matches typename T,
+but does not int N.
 </pre></td></tr>
 
 
@@ -1072,10 +1190,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   int X;
   namespace NS {
-  int Y;
+    int Y;
   }  // namespace NS
-decl(hasDeclContext(translationUnitDecl()))
-  matches "int X", but not "int Y".
+
+The matcher namedDecl(hasDeclContext(translationUnitDecl()))
+matches X and NS,
+but does not match Y.
 </pre></td></tr>
 
 
@@ -1085,17 +1205,22 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   typedef int X;
   using Y = int;
-typeAliasDecl()
-  matches "using Y = int", but not "typedef int X"
+
+The matcher typeAliasDecl()
+matches using Y = int,
+but does not match typedef int X.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('typeAliasTemplateDecl0')"><a name="typeAliasTemplateDecl0Anchor">typeAliasTemplateDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeAliasTemplateDecl.html">TypeAliasTemplateDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="typeAliasTemplateDecl0"><pre>Matches type alias template declarations.
 
-typeAliasTemplateDecl() matches
-  template <typename T>
-  using Y = X<T>;
+Given
+  template <typename T> struct X {};
+  template <typename T> using Y = X<T>;
+
+The matcher typeAliasTemplateDecl()
+matches template <typename T> using Y = X<T>.
 </pre></td></tr>
 
 
@@ -1105,8 +1230,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   typedef int X;
   using Y = int;
-typedefDecl()
-  matches "typedef int X", but not "using Y = int"
+
+The matcher typedefDecl()
+matches typedef int X,
+but does not match using Y = int.
 </pre></td></tr>
 
 
@@ -1116,8 +1243,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   typedef int X;
   using Y = int;
-typedefNameDecl()
-  matches "typedef int X" and "using Y = int"
+
+The matcher typedefNameDecl()
+matches typedef int X and using Y = int.
 </pre></td></tr>
 
 
@@ -1133,8 +1261,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
   struct S : private Base<T> {
     using typename Base<T>::Foo;
   };
-unresolvedUsingTypenameDecl()
-  matches using Base<T>::Foo </pre></td></tr>
+
+The matcher unresolvedUsingTypenameDecl()
+  matches using typename Base<T>::Foo
+</pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('unresolvedUsingValueDecl0')"><a name="unresolvedUsingValueDecl0Anchor">unresolvedUsingValueDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingValueDecl.html">UnresolvedUsingValueDecl</a>>...</td></tr>
@@ -1145,8 +1275,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
   class C : private X {
     using X::x;
   };
-unresolvedUsingValueDecl()
-  matches using X::x </pre></td></tr>
+
+The matcher unresolvedUsingValueDecl()
+  matches using X::x
+</pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('usingDecl0')"><a name="usingDecl0Anchor">usingDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UsingDecl.html">UsingDecl</a>>...</td></tr>
@@ -1155,8 +1287,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   namespace X { int x; }
   using X::x;
-usingDecl()
-  matches using X::x </pre></td></tr>
+
+The matcher usingDecl()
+  matches using X::x
+</pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('usingDirectiveDecl0')"><a name="usingDirectiveDecl0Anchor">usingDirectiveDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UsingDirectiveDecl.html">UsingDirectiveDecl</a>>...</td></tr>
@@ -1165,26 +1299,34 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   namespace X { int x; }
   using namespace X;
-usingDirectiveDecl()
-  matches using namespace X </pre></td></tr>
+
+The matcher usingDirectiveDecl()
+  matches using namespace X
+</pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('usingEnumDecl0')"><a name="usingEnumDecl0Anchor">usingEnumDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UsingEnumDecl.html">UsingEnumDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="usingEnumDecl0"><pre>Matches using-enum declarations.
 
 Given
-  namespace X { enum x {...}; }
+  namespace X { enum x { val1, val2 }; }
   using enum X::x;
-usingEnumDecl()
-  matches using enum X::x </pre></td></tr>
+
+The matcher usingEnumDecl()
+  matches using enum X::x
+</pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('valueDecl0')"><a name="valueDecl0Anchor">valueDecl</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="valueDecl0"><pre>Matches any value declaration.
 
-Example matches A, B, C and F
+Given
   enum X { A, B, C };
   void F();
+  int V = 0;
+The matcher valueDecl()
+matches A, B, C, void F()
+and int V = 0.
 </pre></td></tr>
 
 
@@ -1196,6 +1338,13 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Example matches a
   int a;
+  struct Foo {
+    int x;
+  };
+  void bar(int val);
+
+The matcher varDecl()
+matches int a and int val, but not int x.
 </pre></td></tr>
 
 
@@ -1208,13 +1357,29 @@ <h2 id="decl-matchers">Node Matchers</h2>
     auto f = [x](){};
     auto g = [x = 1](){};
   }
-In the matcher `lambdaExpr(hasAnyCapture(lambdaCapture()))`,
-`lambdaCapture()` matches `x` and `x=1`.
+
+The matcher
+lambdaExpr(hasAnyCapture(lambdaCapture().bind("capture"))),
+matches [x](){} and [x = 1](){},
+with lambdaCapture() matching
+x and x = 1.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>></td><td class="name" onclick="toggle('nestedNameSpecifierLoc0')"><a name="nestedNameSpecifierLoc0Anchor">nestedNameSpecifierLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="nestedNameSpecifierLoc0"><pre>Same as nestedNameSpecifier but matches NestedNameSpecifierLoc.
+
+Given
+  namespace ns {
+    struct A { static void f(); };
+    void A::f() {}
+    void g() { A::f(); }
+  }
+  ns::A a;
+
+
+The matcher nestedNameSpecifierLoc() matches
+A:: twice, and ns:: once.
 </pre></td></tr>
 
 
@@ -1228,8 +1393,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
     void g() { A::f(); }
   }
   ns::A a;
-nestedNameSpecifier()
-  matches "ns::" and both "A::"
+
+The matcher nestedNameSpecifier()
+matches ns and both A
 </pre></td></tr>
 
 
@@ -1237,20 +1403,38 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="ompDefaultClause0"><pre>Matches OpenMP ``default`` clause.
 
 Given
+  void foo() {
+    #pragma omp parallel default(none)
+      ;
+    #pragma omp parallel default(shared)
+      ;
+    #pragma omp parallel default(private)
+      ;
+    #pragma omp parallel default(firstprivate)
+      ;
+    #pragma omp parallel
+      ;
+  }
 
-  #pragma omp parallel default(none)
-  #pragma omp parallel default(shared)
-  #pragma omp parallel default(private)
-  #pragma omp parallel default(firstprivate)
-  #pragma omp parallel
 
-``ompDefaultClause()`` matches ``default(none)``, ``default(shared)``,
-`` default(private)`` and ``default(firstprivate)``
+The matcher
+ompExecutableDirective(hasAnyClause(ompDefaultClause())) matches
+#pragma omp parallel default(none),
+#pragma omp parallel default(shared),
+#pragma omp parallel default(private) and
+#pragma omp parallel default(firstprivate).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('qualType0')"><a name="qualType0Anchor">qualType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="qualType0"><pre>Matches QualTypes in the clang AST.
+
+Given
+  int a = 0;
+  const int b = 1;
+
+The matcher varDecl(hasType(qualType(isConstQualified())))
+matches const int b = 1, but not int a = 0.
 </pre></td></tr>
 
 
@@ -1258,34 +1442,39 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="addrLabelExpr0"><pre>Matches address of label statements (GNU extension).
 
 Given
+void bar();
+void foo() {
   FOO: bar();
   void *ptr = &&FOO;
-  goto *bar;
-addrLabelExpr()
-  matches '&&FOO'
+  goto *ptr;
+}
+The matcher addrLabelExpr()
+matches &&FOO
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('arrayInitIndexExpr0')"><a name="arrayInitIndexExpr0Anchor">arrayInitIndexExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ArrayInitIndexExpr.html">ArrayInitIndexExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="arrayInitIndexExpr0"><pre>The arrayInitIndexExpr consists of two subexpressions: a common expression
-(the source array) that is evaluated once up-front, and a per-element initializer
-that runs once for each array element. Within the per-element initializer,
-the current index may be obtained via an ArrayInitIndexExpr.
+(the source array) that is evaluated once up-front, and a per-element
+initializer that runs once for each array element. Within the per-element
+initializer, the current index may be obtained via an ArrayInitIndexExpr.
 
 Given
-  void testStructBinding() {
+  void testStructuredBinding() {
     int a[2] = {1, 2};
     auto [x, y] = a;
   }
-arrayInitIndexExpr() matches the array index that implicitly iterates
-over the array `a` to copy each element to the anonymous array
-that backs the structured binding `[x, y]` elements of which are
-referred to by their aliases `x` and `y`.
+
+
+The matcher arrayInitIndexExpr() matches the array index
+that implicitly iterates over the array `a` to copy each element to the
+anonymous array that backs the structured binding.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('arrayInitLoopExpr0')"><a name="arrayInitLoopExpr0Anchor">arrayInitLoopExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ArrayInitLoopExpr.html">ArrayInitLoopExpr</a>>...</td></tr>
-<tr><td colspan="4" class="doc" id="arrayInitLoopExpr0"><pre>Matches a loop initializing the elements of an array in a number of contexts:
+<tr><td colspan="4" class="doc" id="arrayInitLoopExpr0"><pre>Matches a loop initializing the elements of an array in a number of
+contexts:
  * in the implicit copy/move constructor for a class with an array member
  * when a lambda-expression captures an array by value
  * when a decomposition declaration decomposes an array
@@ -1293,13 +1482,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   void testLambdaCapture() {
     int a[10];
-    auto Lam1 = [a]() {
-      return;
-    };
+    [a]() {};
   }
-arrayInitLoopExpr() matches the implicit loop that initializes each element of
-the implicit array field inside the lambda object, that represents the array `a`
-captured by value.
+
+The matcher arrayInitLoopExpr() matches the implicit loop that
+initializes each element of the implicit array field inside the lambda
+object, that represents the array a captured by value.
 </pre></td></tr>
 
 
@@ -1307,26 +1495,34 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="arraySubscriptExpr0"><pre>Matches array subscript expressions.
 
 Given
-  int i = a[1];
-arraySubscriptExpr()
-  matches "a[1]"
+  void foo() {
+    int a[2] = {0, 1};
+    int i = a[1];
+  }
+The matcher arraySubscriptExpr()
+matches a[1].
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('asmStmt0')"><a name="asmStmt0Anchor">asmStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AsmStmt.html">AsmStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="asmStmt0"><pre>Matches asm statements.
 
+void foo() {
  int i = 100;
-  __asm("mov al, 2");
-asmStmt()
-  matches '__asm("mov al, 2")'
+  __asm("mov %al, 2");
+}
+The matcher asmStmt()
+matches __asm("mov %al, 2")
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('atomicExpr0')"><a name="atomicExpr0Anchor">atomicExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AtomicExpr.html">AtomicExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="atomicExpr0"><pre>Matches atomic builtins.
-Example matches __atomic_load_n(ptr, 1)
+
+Given
   void foo() { int *ptr; __atomic_load_n(ptr, 1); }
+
+The matcher atomicExpr() matches __atomic_load_n(ptr, 1).
 </pre></td></tr>
 
 
@@ -1337,24 +1533,35 @@ <h2 id="decl-matchers">Node Matchers</h2>
   @autoreleasepool {
     int x = 0;
   }
-autoreleasePoolStmt(stmt()) matches the declaration of "x"
-inside the autorelease pool.
+
+The matcher autoreleasePoolStmt(stmt()) matches the declaration of
+int x = 0 inside the autorelease pool.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('binaryConditionalOperator0')"><a name="binaryConditionalOperator0Anchor">binaryConditionalOperator</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BinaryConditionalOperator.html">BinaryConditionalOperator</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="binaryConditionalOperator0"><pre>Matches binary conditional operator expressions (GNU extension).
 
-Example matches a ?: b
-  (a ?: b) + 42;
+Given
+  int f(int a, int b) {
+    return (a ?: b) + 42;
+  }
+
+The matcher binaryConditionalOperator() matches a ?: b.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('binaryOperator0')"><a name="binaryOperator0Anchor">binaryOperator</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="binaryOperator0"><pre>Matches binary operator expressions.
 
-Example matches a || b
-  !(a || b)
+Given
+  void foo(bool a, bool b) {
+    !(a || b);
+  }
+
+
+The matcher binaryOperator() matches a || b.
+
 See also the binaryOperation() matcher for more-general matching.
 </pre></td></tr>
 
@@ -1362,8 +1569,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('blockExpr0')"><a name="blockExpr0Anchor">blockExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockExpr.html">BlockExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="blockExpr0"><pre>Matches a reference to a block.
 
-Example: matches "^{}":
+Given
   void f() { ^{}(); }
+
+
+The matcher blockExpr() matches ^{}.
 </pre></td></tr>
 
 
@@ -1371,17 +1581,23 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="breakStmt0"><pre>Matches break statements.
 
 Given
+void foo() {
   while (true) { break; }
-breakStmt()
-  matches 'break'
+}
+
+The matcher breakStmt()
+matches break
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cStyleCastExpr0')"><a name="cStyleCastExpr0Anchor">cStyleCastExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CStyleCastExpr.html">CStyleCastExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cStyleCastExpr0"><pre>Matches a C-style cast expression.
 
-Example: Matches (int) 2.2f in
+Given
   int i = (int) 2.2f;
+
+The matcher cStyleCastExpr()
+matches (int) 2.2f.
 </pre></td></tr>
 
 
@@ -1389,9 +1605,16 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="callExpr0"><pre>Matches call expressions.
 
 Example matches x.y() and y()
-  X x;
-  x.y();
-  y();
+  struct X { void foo(); };
+  void bar();
+  void foobar() {
+    X x;
+    x.foo();
+    bar();
+  }
+
+The matcher callExpr()
+matches x.foo() and bar();
 </pre></td></tr>
 
 
@@ -1399,22 +1622,41 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="caseStmt0"><pre>Matches case statements inside switch statements.
 
 Given
+void foo(int a) {
   switch(a) { case 42: break; default: break; }
-caseStmt()
-  matches 'case 42:'.
+}
+The matcher caseStmt()
+matches case 42: break.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('castExpr0')"><a name="castExpr0Anchor">castExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CastExpr.html">CastExpr</a>>...</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;
-  const_cast<Expr *>(SubExpr);
-  char c = 0;
-but does not match
-  int i = (0);
-  int k = 0;
+Given
+  struct S {};
+  const S* s;
+  S* s2 = const_cast<S*>(s);
+
+  const int val = 0;
+  char val0 = 1;
+  char val1 = (char)2;
+  char val2 = static_cast<char>(3);
+  int* val3 = reinterpret_cast<int*>(4);
+  char val4 = char(5);
+
+
+The matcher castExpr()
+matches
+const_cast<S*>(s) and the implicit l- to r-value cast for s,
+the implicit cast to char for the initializer 1,
+the c-style cast (char)2 and it's implicit cast to char
+(part of the c-style cast) 2,
+static_cast<char>(3) and it's implicit cast to char
+(part of the static_cast) 3,
+reinterpret_cast<int*>(4),
+char(5) and it's implicit cast to char
+(part of the functional cast) 5.
 </pre></td></tr>
 
 
@@ -1424,14 +1666,24 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Not matching Hex-encoded chars (e.g. 0x1234, which is a IntegerLiteral),
 though.
 
-Example matches 'a', L'a'
+Given
   char ch = 'a';
   wchar_t chw = L'a';
+
+
+The matcher characterLiteral() matches 'a' and
+L'a'.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('chooseExpr0')"><a name="chooseExpr0Anchor">chooseExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ChooseExpr.html">ChooseExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="chooseExpr0"><pre>Matches GNU __builtin_choose_expr.
+
+Given
+  void f() { (void)__builtin_choose_expr(1, 2, 3); }
+
+The matcher chooseExpr() matches
+__builtin_choose_expr(1, 2, 3).
 </pre></td></tr>
 
 
@@ -1439,9 +1691,45 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="coawaitExpr0"><pre>Matches co_await expressions.
 
 Given
-  co_await 1;
-coawaitExpr()
-  matches 'co_await 1'
+  namespace std {
+  template <typename T = void>
+  struct coroutine_handle {
+      static constexpr coroutine_handle from_address(void* addr) {
+        return {};
+      }
+  };
+
+  struct always_suspend {
+      bool await_ready() const noexcept;
+      bool await_resume() const noexcept;
+      template <typename T>
+      bool await_suspend(coroutine_handle<T>) const noexcept;
+  };
+
+  template <typename T>
+  struct coroutine_traits {
+      using promise_type = T::promise_type;
+  };
+  }  // namespace std
+
+  struct generator {
+      struct promise_type {
+          std::always_suspend yield_value(int&&);
+          std::always_suspend initial_suspend() const noexcept;
+          std::always_suspend final_suspend() const noexcept;
+          void return_void();
+          void unhandled_exception();
+          generator get_return_object();
+      };
+  };
+
+  std::always_suspend h();
+
+  generator g() { co_await h(); }
+
+The matcher
+coawaitExpr(has(callExpr(callee(functionDecl(hasName("h"))))))
+matches co_await h().
 </pre></td></tr>
 
 
@@ -1449,35 +1737,48 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="compoundLiteralExpr0"><pre>Matches compound (i.e. non-scalar) literals
 
 Example match: {1}, (1, 2)
-  int array[4] = {1};
-  vector int myvec = (vector int)(1, 2);
+  struct vector { int x; int y; };
+  struct vector myvec = (struct vector){ 1, 2 };
+
+The matcher compoundLiteralExpr()
+matches (struct vector){ 1, 2 }.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('compoundStmt0')"><a name="compoundStmt0Anchor">compoundStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">CompoundStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="compoundStmt0"><pre>Matches compound statements.
 
-Example matches '{}' and '{{}}' in 'for (;;) {{}}'
-  for (;;) {{}}
+Given
+void foo() { for (;;) {{}} }
+
+The matcher compoundStmt() matches
+{ for (;;) {{}} }, {{}} and {}.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('conditionalOperator0')"><a name="conditionalOperator0Anchor">conditionalOperator</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ConditionalOperator.html">ConditionalOperator</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="conditionalOperator0"><pre>Matches conditional operator expressions.
 
-Example matches a ? b : c
-  (a ? b : c) + 42
+Given
+  int f(int a, int b, int c) {
+    return (a ? b : c) + 42;
+  }
+
+The matcher conditionalOperator() matches a ? b : c.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('constantExpr0')"><a name="constantExpr0Anchor">constantExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ConstantExpr.html">ConstantExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="constantExpr0"><pre>Matches a constant expression wrapper.
 
-Example matches the constant in the case statement:
-    (matcher = constantExpr())
-  switch (a) {
-  case 37: break;
+Given
+  void f(int a) {
+    switch (a) {
+      case 37: break;
+    }
   }
+
+The matcher constantExpr() matches 37.
 </pre></td></tr>
 
 
@@ -1485,14 +1786,26 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="continueStmt0"><pre>Matches continue statements.
 
 Given
+void foo() {
   while (true) { continue; }
-continueStmt()
-  matches 'continue'
+}
+
+The matcher continueStmt()
+matches continue
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('convertVectorExpr0')"><a name="convertVectorExpr0Anchor">convertVectorExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ConvertVectorExpr.html">ConvertVectorExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="convertVectorExpr0"><pre>Matches builtin function __builtin_convertvector.
+
+Given
+  typedef double vector4double __attribute__((__vector_size__(32)));
+  typedef float  vector4float  __attribute__((__vector_size__(16)));
+  vector4float vf;
+  void f() { (void)__builtin_convertvector(vf, vector4double); }
+
+The matcher convertVectorExpr() matches
+__builtin_convertvector(vf, vector4double).
 </pre></td></tr>
 
 
@@ -1500,19 +1813,85 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="coreturnStmt0"><pre>Matches co_return statements.
 
 Given
-  while (true) { co_return; }
-coreturnStmt()
-  matches 'co_return'
+  namespace std {
+  template <typename T = void>
+  struct coroutine_handle {
+      static constexpr coroutine_handle from_address(void* addr) {
+        return {};
+      }
+  };
+
+  struct always_suspend {
+      bool await_ready() const noexcept;
+      bool await_resume() const noexcept;
+      template <typename T>
+      bool await_suspend(coroutine_handle<T>) const noexcept;
+  };
+
+  template <typename T>
+  struct coroutine_traits {
+      using promise_type = T::promise_type;
+  };
+  }  // namespace std
+
+  struct generator {
+      struct promise_type {
+          void return_value(int v);
+          std::always_suspend yield_value(int&&);
+          std::always_suspend initial_suspend() const noexcept;
+          std::always_suspend final_suspend() const noexcept;
+          void unhandled_exception();
+          generator get_return_object();
+      };
+  };
+
+  generator f() {
+      co_return 10;
+  }
+
+
+The matcher coreturnStmt(has(integerLiteral()))
+matches co_return 10
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('coroutineBodyStmt0')"><a name="coroutineBodyStmt0Anchor">coroutineBodyStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CoroutineBodyStmt.html">CoroutineBodyStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="coroutineBodyStmt0"><pre>Matches coroutine body statements.
 
-coroutineBodyStmt() matches the coroutine below
-  generator<int> gen() {
-    co_return;
-  }
+Given
+  namespace std {
+  template <typename T = void>
+  struct coroutine_handle {
+      static constexpr coroutine_handle from_address(void* addr) {
+        return {};
+      }
+  };
+
+  struct suspend_always {
+      bool await_ready() const noexcept;
+      bool await_resume() const noexcept;
+      template <typename T>
+      bool await_suspend(coroutine_handle<T>) const noexcept;
+  };
+
+  template <typename...>
+  struct coroutine_traits {
+      struct promise_type {
+          std::suspend_always initial_suspend() const noexcept;
+          std::suspend_always final_suspend() const noexcept;
+          void return_void();
+          void unhandled_exception();
+          coroutine_traits get_return_object();
+      };
+  };
+  }  // namespace std
+
+  void f() { while (true) { co_return; } }
+
+
+
+The matcher coroutineBodyStmt() matches
+{ while (true) { co_return; } }.
 </pre></td></tr>
 
 
@@ -1520,27 +1899,77 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="coyieldExpr0"><pre>Matches co_yield expressions.
 
 Given
-  co_yield 1;
-coyieldExpr()
-  matches 'co_yield 1'
+  namespace std {
+  template <typename T = void>
+  struct coroutine_handle {
+      static constexpr coroutine_handle from_address(void* addr) {
+        return {};
+      }
+  };
+
+  struct always_suspend {
+      bool await_ready() const noexcept;
+      bool await_resume() const noexcept;
+      template <typename T>
+      bool await_suspend(coroutine_handle<T>) const noexcept;
+  };
+
+  template <typename T>
+  struct coroutine_traits {
+      using promise_type = T::promise_type;
+  };
+  }  // namespace std
+
+  struct generator {
+      struct promise_type {
+          std::always_suspend yield_value(int&&);
+          std::always_suspend initial_suspend() const noexcept;
+          std::always_suspend final_suspend() const noexcept;
+          void return_void();
+          void unhandled_exception();
+          generator get_return_object();
+      };
+  };
+
+  generator f() {
+      while (true) {
+          co_yield 10;
+      }
+  }
+
+The matcher coyieldExpr()
+matches co_yield 10
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cudaKernelCallExpr0')"><a name="cudaKernelCallExpr0Anchor">cudaKernelCallExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CUDAKernelCallExpr.html">CUDAKernelCallExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cudaKernelCallExpr0"><pre>Matches CUDA kernel call expression.
 
-Example matches,
-  kernel<<<i,j>>>();
+Given
+  __global__ void kernel() {}
+  void f() {
+    kernel<<<32,32>>>();
+  }
+
+The matcher cudaKernelCallExpr()
+matches kernel<<<i, k>>>()
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxBindTemporaryExpr0')"><a name="cxxBindTemporaryExpr0Anchor">cxxBindTemporaryExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBindTemporaryExpr.html">CXXBindTemporaryExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxBindTemporaryExpr0"><pre>Matches nodes where temporaries are created.
 
-Example matches FunctionTakesString(GetStringByValue())
-    (matcher = cxxBindTemporaryExpr())
-  FunctionTakesString(GetStringByValue());
-  FunctionTakesStringByPointer(GetStringPointer());
+Given
+  struct S {
+    S() { }  // User defined constructor makes S non-POD.
+    ~S() { } // User defined destructor makes it non-trivial.
+  };
+  void test() {
+    const S &s_ref = S(); // Requires a CXXBindTemporaryExpr.
+  }
+
+The matcher cxxBindTemporaryExpr()
+matches the constructor call S().
 </pre></td></tr>
 
 
@@ -1548,49 +1977,71 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="cxxBoolLiteral0"><pre>Matches bool literals.
 
 Example matches true
-  true
+  bool Flag = true;
+
+
+The matcher cxxBoolLiteral() matches true.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxCatchStmt0')"><a name="cxxCatchStmt0Anchor">cxxCatchStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCatchStmt.html">CXXCatchStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxCatchStmt0"><pre>Matches catch statements.
 
+void foo() {
   try {} catch(int i) {}
-cxxCatchStmt()
-  matches 'catch(int i)'
+}
+
+The matcher cxxCatchStmt()
+matches catch(int i) {}
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxConstCastExpr0')"><a name="cxxConstCastExpr0Anchor">cxxConstCastExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstCastExpr.html">CXXConstCastExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxConstCastExpr0"><pre>Matches a const_cast expression.
 
-Example: Matches const_cast<int*>(&r) in
+Given
   int n = 42;
   const int &r(n);
   int* p = const_cast<int*>(&r);
+
+
+The matcher cxxConstCastExpr()
+matches const_cast<int*>(&r).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxConstructExpr0')"><a name="cxxConstructExpr0Anchor">cxxConstructExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxConstructExpr0"><pre>Matches constructor call expressions (including implicit ones).
 
-Example matches string(ptr, n) and ptr within arguments of f
-    (matcher = cxxConstructExpr())
+Given
+  struct string {
+    string(const char*);
+    string(const char*s, int n);
+  };
   void f(const string &a, const string &b);
-  char *ptr;
-  int n;
-  f(string(ptr, n), ptr);
+  void foo(char *ptr, int n) {
+    f(string(ptr, n), ptr);
+  }
+
+
+The matcher cxxConstructExpr() matches string(ptr, n)
+and ptr within arguments of f .
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxDefaultArgExpr0')"><a name="cxxDefaultArgExpr0Anchor">cxxDefaultArgExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXDefaultArgExpr.html">CXXDefaultArgExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxDefaultArgExpr0"><pre>Matches the value of a default argument at the call site.
 
-Example matches the CXXDefaultArgExpr placeholder inserted for the
-    default value of the second parameter in the call expression f(42)
-    (matcher = cxxDefaultArgExpr())
+Given
   void f(int x, int y = 0);
-  f(42);
+  void g() {
+    f(42);
+  }
+
+
+The matcher callExpr(has(cxxDefaultArgExpr()))
+matches the CXXDefaultArgExpr placeholder inserted for the default value
+of the second parameter in the call expression f(42).
 </pre></td></tr>
 
 
@@ -1598,9 +2049,17 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="cxxDeleteExpr0"><pre>Matches delete expressions.
 
 Given
-  delete X;
-cxxDeleteExpr()
-  matches 'delete X'.
+  void* operator new(decltype(sizeof(void*)));
+  void operator delete(void*);
+  struct X {};
+  void foo() {
+    auto* x = new X;
+    delete x;
+  }
+
+
+The matcher cxxDeleteExpr()
+matches delete x.
 </pre></td></tr>
 
 
@@ -1610,7 +2069,8 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   template <class T> void f() { T t; t.g(); }
-cxxDependentScopeMemberExpr()
+
+The matcher cxxDependentScopeMemberExpr()
   matches t.g
 </pre></td></tr>
 
@@ -1618,53 +2078,83 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxDynamicCastExpr0')"><a name="cxxDynamicCastExpr0Anchor">cxxDynamicCastExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXDynamicCastExpr.html">CXXDynamicCastExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxDynamicCastExpr0"><pre>Matches a dynamic_cast expression.
 
-Example:
-  cxxDynamicCastExpr()
-matches
-  dynamic_cast<D*>(&b);
-in
+Given
   struct B { virtual ~B() {} }; struct D : B {};
   B b;
   D* p = dynamic_cast<D*>(&b);
+
+
+The matcher cxxDynamicCastExpr()
+matches dynamic_cast<D*>(&b).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxFoldExpr0')"><a name="cxxFoldExpr0Anchor">cxxFoldExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxFoldExpr0"><pre>Matches C++17 fold expressions.
 
-Example matches `(0 + ... + args)`:
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
   }
+
+
+The matcher cxxFoldExpr() matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxForRangeStmt0')"><a name="cxxForRangeStmt0Anchor">cxxForRangeStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxForRangeStmt0"><pre>Matches range-based for statements.
 
-cxxForRangeStmt() matches 'for (auto a : i)'
-  int i[] =  {1, 2, 3}; for (auto a : i);
-  for(int j = 0; j < 5; ++j);
+Given
+  void foo() {
+    int i[] =  {1, 2, 3}; for (auto a : i);
+    for(int j = 0; j < 5; ++j);
+  }
+
+The matcher cxxForRangeStmt()
+matches for (auto a : i);
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxFunctionalCastExpr0')"><a name="cxxFunctionalCastExpr0Anchor">cxxFunctionalCastExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxFunctionalCastExpr0"><pre>Matches functional cast expressions
 
-Example: Matches Foo(bar);
-  Foo f = bar;
-  Foo g = (Foo) bar;
-  Foo h = Foo(bar);
+Given
+  struct Foo {
+    Foo(int x);
+  };
+
+  void foo(int bar) {
+    Foo f = bar;
+    Foo g = (Foo) bar;
+    Foo h = Foo(bar);
+  }
+
+
+The matcher cxxFunctionalCastExpr()
+matches Foo(bar).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxMemberCallExpr0')"><a name="cxxMemberCallExpr0Anchor">cxxMemberCallExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxMemberCallExpr0"><pre>Matches member call expressions.
 
-Example matches x.y()
-  X x;
-  x.y();
+Given
+  struct X {
+    void y();
+    void m() { y(); }
+  };
+  void f();
+  void g() {
+    X x;
+    x.y();
+    f();
+  }
+
+
+The matcher cxxMemberCallExpr() matches x.y() and
+y(), but not f().
 </pre></td></tr>
 
 
@@ -1672,9 +2162,15 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="cxxNewExpr0"><pre>Matches new expressions.
 
 Given
-  new X;
-cxxNewExpr()
-  matches 'new X'.
+  void* operator new(decltype(sizeof(void*)));
+  struct X {};
+  void foo() {
+    auto* x = new X;
+  }
+
+
+The matcher cxxNewExpr()
+matches new X.
 </pre></td></tr>
 
 
@@ -1687,14 +2183,24 @@ <h2 id="decl-matchers">Node Matchers</h2>
   bool c() noexcept(false);
   bool d() noexcept(noexcept(a()));
   bool e = noexcept(b()) || noexcept(c());
-cxxNoexceptExpr()
-  matches `noexcept(a())`, `noexcept(b())` and `noexcept(c())`.
-  doesn't match the noexcept specifier in the declarations a, b, c or d.
+
+The matcher cxxNoexceptExpr()
+matches noexcept(a()), noexcept(b()) and
+noexcept(c()), but does not match the noexcept specifier in the
+declarations a, b, c or d.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxNullPtrLiteralExpr0')"><a name="cxxNullPtrLiteralExpr0Anchor">cxxNullPtrLiteralExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNullPtrLiteralExpr.html">CXXNullPtrLiteralExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxNullPtrLiteralExpr0"><pre>Matches nullptr literal.
+
+Given
+  int a = 0;
+  int* b = 0;
+  int *c = nullptr;
+
+
+The matcher cxxNullPtrLiteralExpr() matches nullptr.
 </pre></td></tr>
 
 
@@ -1706,11 +2212,16 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Currently it does not match operators such as new delete.
 FIXME: figure out why these do not match?
 
-Example matches both operator<<((o << b), c) and operator<<(o, b)
-    (matcher = cxxOperatorCallExpr())
+Given
+  struct ostream;
   ostream &operator<< (ostream &out, int i) { };
-  ostream &o; int b = 1, c = 1;
-  o << b << c;
+  void f(ostream& o, int b, int c) {
+    o << b << c;
+  }
+
+
+The matcher cxxOperatorCallExpr() matches o << b << c
+and o << b.
 See also the binaryOperation() matcher for more-general matching of binary
 uses of this AST node.
 </pre></td></tr>
@@ -1725,6 +2236,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Example matches reinterpret_cast<char*>(&p) in
   void* p = reinterpret_cast<char*>(&p);
+
+
+The matcher cxxReinterpretCastExpr()
+matches reinterpret_cast<char*>(&p).
 </pre></td></tr>
 
 
@@ -1732,16 +2247,20 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="cxxRewrittenBinaryOperator0"><pre>Matches rewritten binary operators
 
 Example matches use of "<":
-  #include <compare>
   struct HasSpaceshipMem {
     int a;
-    constexpr auto operator<=>(const HasSpaceshipMem&) const = default;
+    constexpr bool operator==(const HasSpaceshipMem&) const = default;
   };
   void compare() {
     HasSpaceshipMem hs1, hs2;
-    if (hs1 < hs2)
+    if (hs1 != hs2)
         return;
   }
+
+
+The matcher cxxRewrittenBinaryOperator() matches
+hs1 != hs2.
+
 See also the binaryOperation() matcher for more-general matching
 of this AST node.
 </pre></td></tr>
@@ -1753,12 +2272,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 See also: hasDestinationType
 See also: reinterpretCast
 
-Example:
-  cxxStaticCastExpr()
-matches
-  static_cast<long>(8)
-in
+Given
   long eight(static_cast<long>(8));
+
+
+The matcher cxxStaticCastExpr()
+matches static_cast<long>(8).
 </pre></td></tr>
 
 
@@ -1766,69 +2285,110 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="cxxStdInitializerListExpr0"><pre>Matches C++ initializer list expressions.
 
 Given
-  std::vector<int> a({ 1, 2, 3 });
-  std::vector<int> b = { 4, 5 };
+  namespace std {
+    template <typename T>
+    class initializer_list {
+      const T* begin;
+      const T* end;
+    };
+  }
+  template <typename T> class vector {
+    public: vector(std::initializer_list<T>) {}
+  };
+
+  vector<int> a({ 1, 2, 3 });
+  vector<int> b = { 4, 5 };
   int c[] = { 6, 7 };
-  std::pair<int, int> d = { 8, 9 };
-cxxStdInitializerListExpr()
-  matches "{ 1, 2, 3 }" and "{ 4, 5 }"
+  struct pair { int x; int y; };
+  pair d = { 8, 9 };
+
+The matcher cxxStdInitializerListExpr()
+matches { 1, 2, 3 } and { 4, 5 }.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxTemporaryObjectExpr0')"><a name="cxxTemporaryObjectExpr0Anchor">cxxTemporaryObjectExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXTemporaryObjectExpr.html">CXXTemporaryObjectExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxTemporaryObjectExpr0"><pre>Matches functional cast expressions having N != 1 arguments
 
-Example: Matches Foo(bar, bar)
-  Foo h = Foo(bar, bar);
+Given
+  struct Foo {
+    Foo(int x, int y);
+  };
+
+  void foo(int bar) {
+    Foo h = Foo(bar, bar);
+  }
+
+
+The matcher cxxTemporaryObjectExpr()
+matches Foo(bar, bar).
 </pre></td></tr>
 
 
-<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxThisExpr0')"><a name="cxxThisExpr0Anchor">cxxThisExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXThisExpr.html">CXXThisExpr</a>>...</td></tr>
-<tr><td colspan="4" class="doc" id="cxxThisExpr0"><pre>Matches implicit and explicit this expressions.
+<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxThisExpr0')"><a name="cxxThisExpr0Anchor">cxxThisExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXThisExpr.html">CXXThisExpr</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="cxxThisExpr0"><pre>Matches implicit and explicit this expressions.
+
+Given
+  struct foo {
+    int i;
+    int f() { return i; }
+    int g() { return this->i; }
+  };
+
 
-Example matches the implicit this expression in "return i".
-    (matcher = cxxThisExpr())
-struct foo {
-  int i;
-  int f() { return i; }
-};
+The matcher cxxThisExpr()
+matches this of this->i and the implicit this expression
+of i.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxThrowExpr0')"><a name="cxxThrowExpr0Anchor">cxxThrowExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXThrowExpr.html">CXXThrowExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxThrowExpr0"><pre>Matches throw expressions.
 
+void foo() {
   try { throw 5; } catch(int i) {}
-cxxThrowExpr()
-  matches 'throw 5'
+}
+
+The matcher cxxThrowExpr()
+matches throw 5
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxTryStmt0')"><a name="cxxTryStmt0Anchor">cxxTryStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXTryStmt.html">CXXTryStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxTryStmt0"><pre>Matches try statements.
 
+void foo() {
   try {} catch(int i) {}
-cxxTryStmt()
-  matches 'try {}'
+}
+
+The matcher cxxTryStmt()
+matches try {} catch(int i) {}
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('cxxUnresolvedConstructExpr0')"><a name="cxxUnresolvedConstructExpr0Anchor">cxxUnresolvedConstructExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXUnresolvedConstructExpr.html">CXXUnresolvedConstructExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="cxxUnresolvedConstructExpr0"><pre>Matches unresolved constructor call expressions.
 
-Example matches T(t) in return statement of f
-    (matcher = cxxUnresolvedConstructExpr())
+Given
   template <typename T>
   void f(const T& t) { return T(t); }
+
+
+The matcher cxxUnresolvedConstructExpr() matches
+T(t).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('declRefExpr0')"><a name="declRefExpr0Anchor">declRefExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="declRefExpr0"><pre>Matches expressions that refer to declarations.
 
-Example matches x in if (x)
-  bool x;
-  if (x) {}
+Given
+  void f(bool x) {
+    if (x) {}
+  }
+
+
+The matcher declRefExpr() matches x.
 </pre></td></tr>
 
 
@@ -1836,9 +2396,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="declStmt0"><pre>Matches declaration statements.
 
 Given
-  int a;
-declStmt()
-  matches 'int a'.
+  void foo() {
+    int a;
+  }
+The matcher declStmt()
+matches int a;.
 </pre></td></tr>
 
 
@@ -1846,22 +2408,75 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="defaultStmt0"><pre>Matches default statements inside switch statements.
 
 Given
+void foo(int a) {
   switch(a) { case 42: break; default: break; }
-defaultStmt()
-  matches 'default:'.
+}
+The matcher defaultStmt()
+matches default: break.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('dependentCoawaitExpr0')"><a name="dependentCoawaitExpr0Anchor">dependentCoawaitExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DependentCoawaitExpr.html">DependentCoawaitExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="dependentCoawaitExpr0"><pre>Matches co_await expressions where the type of the promise is dependent
+
+Given
+  namespace std {
+  template <typename T = void>
+  struct coroutine_handle {
+      static constexpr coroutine_handle from_address(void* addr) {
+        return {};
+      }
+  };
+
+  struct always_suspend {
+      bool await_ready() const noexcept;
+      bool await_resume() const noexcept;
+      template <typename T>
+      bool await_suspend(coroutine_handle<T>) const noexcept;
+  };
+
+  template <typename T>
+  struct coroutine_traits {
+      using promise_type = T::promise_type;
+  };
+  }  // namespace std
+
+  template <typename T>
+  struct generator {
+      struct promise_type {
+          std::always_suspend yield_value(int&&);
+          std::always_suspend initial_suspend() const noexcept;
+          std::always_suspend final_suspend() const noexcept;
+          void return_void();
+          void unhandled_exception();
+          generator get_return_object();
+      };
+  };
+
+  template <typename T>
+  std::always_suspend h();
+
+  template <>
+  std::always_suspend h<void>();
+
+  template<typename T>
+  generator<T> g() { co_await h<T>(); }
+
+The matcher dependentCoawaitExpr()
+matches co_await h<T>().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('designatedInitExpr0')"><a name="designatedInitExpr0Anchor">designatedInitExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DesignatedInitExpr.html">DesignatedInitExpr</a>>...</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 point2 { double x; double y; };
+  struct point2 ptarray[10] = { [0].x = 1.0 };
+  struct point2 pt = { .x = 2.0 };
+
+The matcher designatedInitExpr()
+matches [0].x = 1.0 and .x = 2.0.
 </pre></td></tr>
 
 
@@ -1869,9 +2484,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="doStmt0"><pre>Matches do statements.
 
 Given
+void foo() {
   do {} while (true);
-doStmt()
-  matches 'do {} while(true)'
+}
+
+The matcher doStmt()
+matches do {} while (true)
 </pre></td></tr>
 
 
@@ -1889,18 +2507,36 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 See also: hasDestinationType.
 
-Example: matches all five of the casts in
-  int((int)(reinterpret_cast<int>(static_cast<int>(const_cast<int>(42)))))
-but does not match the implicit conversion in
-  long ell = 42;
+  struct S {};
+  const S* s;
+  S* s2 = const_cast<S*>(s);
+
+  const int val = 0;
+  char val0 = val;
+  char val1 = (char)val;
+  char val2 = static_cast<char>(val);
+  int* val3 = reinterpret_cast<int*>(val);
+  char val4 = char(val);
+
+
+The matcher explicitCastExpr()
+matches (char)val, static_cast<char>(val),
+reinterpret_cast<int*>(val), const_cast<S*>(s)
+and char(val), but not the initialization of val0 with
+val.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('expr0')"><a name="expr0Anchor">expr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="expr0"><pre>Matches expressions.
 
-Example matches x()
-  void f() { x(); }
+Given
+  int f(int x, int y) { return x + y; }
+
+The matcher expr() matches x + y once,
+x twice and y twice, matching the
+DeclRefExpr , and the ImplicitCastExpr that does an l- to r-value
+cast.
 </pre></td></tr>
 
 
@@ -1909,12 +2545,33 @@ <h2 id="decl-matchers">Node Matchers</h2>
 of the sub-expression's evaluation.
 
 Example matches std::string()
-  const std::string str = std::string();
+  struct A { ~A(); };
+  void f(A);
+  void g(A&);
+  void h() {
+    A a = A{};
+    f(A{});
+    f(a);
+    g(a);
+  }
+
+
+The matcher exprWithCleanups() matches A{},
+f(A{}) and f(a),
+but does not match passing g(a).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('fixedPointLiteral0')"><a name="fixedPointLiteral0Anchor">fixedPointLiteral</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FixedPointLiteral.html">FixedPointLiteral</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="fixedPointLiteral0"><pre>Matches fixed point literals
+
+Given
+  void f() {
+    0.0k;
+  }
+
+
+The matcher fixedPointLiteral() matches 0.0k.
 </pre></td></tr>
 
 
@@ -1922,27 +2579,62 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="floatLiteral0"><pre>Matches float literals of all sizes / encodings, e.g.
 1.0, 1.0f, 1.0L and 1e10.
 
-Does not match implicit conversions such as
-  float a = 10;
+Given
+  int a = 1.0;
+  int b = 1.0F;
+  int c = 1.0L;
+  int d = 1e10;
+  int e = 1;
+
+The matcher floatLiteral() matches
+1.0, 1.0F, 1.0L and 1e10, but does not match
+1.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('forStmt0')"><a name="forStmt0Anchor">forStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ForStmt.html">ForStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="forStmt0"><pre>Matches for statements.
 
-Example matches 'for (;;) {}'
-  for (;;) {}
-  int i[] =  {1, 2, 3}; for (auto a : i);
+Given
+  void foo() {
+    for (;;) {}
+    int i[] =  {1, 2, 3}; for (auto a : i);
+  }
+
+
+The matcher forStmt() matches for (;;) {},
+but not for (auto a : i);.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('genericSelectionExpr0')"><a name="genericSelectionExpr0Anchor">genericSelectionExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1GenericSelectionExpr.html">GenericSelectionExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="genericSelectionExpr0"><pre>Matches C11 _Generic expression.
+
+Given
+  double fdouble(double);
+  float ffloat(float);
+  #define GENERIC_MACRO(X) _Generic((X), double: fdouble, float: ffloat)(X)
+
+  void f() {
+      GENERIC_MACRO(0.0);
+      GENERIC_MACRO(0.0F);
+  }
+
+
+The matcher genericSelectionExpr() matches
+the generic selection expression that is expanded in
+GENERIC_MACRO(0.0) and GENERIC_MACRO(0.0F).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('gnuNullExpr0')"><a name="gnuNullExpr0Anchor">gnuNullExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1GNUNullExpr.html">GNUNullExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="gnuNullExpr0"><pre>Matches GNU __null expression.
+
+Given
+  auto val = __null;
+
+
+The matcher gnuNullExpr() matches __null.
 </pre></td></tr>
 
 
@@ -1950,24 +2642,39 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="gotoStmt0"><pre>Matches goto statements.
 
 Given
+void bar();
+void foo() {
   goto FOO;
   FOO: bar();
-gotoStmt()
-  matches 'goto FOO'
+}
+The matcher gotoStmt()
+matches goto FOO
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('ifStmt0')"><a name="ifStmt0Anchor">ifStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="ifStmt0"><pre>Matches if statements.
 
-Example matches 'if (x) {}'
-  if (x) {}
+Given
+  void foo(int x) {
+    if (x) {}
+  }
+
+The matcher ifStmt() matches if (x) {}.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('imaginaryLiteral0')"><a name="imaginaryLiteral0Anchor">imaginaryLiteral</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ImaginaryLiteral.html">ImaginaryLiteral</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="imaginaryLiteral0"><pre>Matches imaginary literals, which are based on integer and floating
 point literals e.g.: 1i, 1.0i
+
+Given
+  auto a = 1i;
+  auto b = 1.0i;
+
+
+The matcher imaginaryLiteral() matches 1i and
+1.0i.
 </pre></td></tr>
 
 
@@ -1976,6 +2683,17 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 This matches many different places, including function call return value
 eliding, as well as any type conversions.
+
+void f(int);
+void g(int val1, int val2) {
+  unsigned int a = val1;
+  f(val2);
+}
+
+The matcher implicitCastExpr()
+matches val1 for the implicit cast from an l- to an r-value
+and for the cast to int}, f for the function pointer
+decay, and val2 for the cast from an l- to an r-value.
 </pre></td></tr>
 
 
@@ -1983,9 +2701,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="implicitValueInitExpr0"><pre>Matches implicit initializers of init list expressions.
 
 Given
-  point ptarray[10] = { [2].y = 1.0, [2].x = 2.0, [0].x = 1.0 };
-implicitValueInitExpr()
-  matches "[0].y" (implicitly)
+  struct point { double x; double y; };
+  struct point pt = { .x = 42.0 };
+The matcher
+initListExpr(has(implicitValueInitExpr().bind("implicit")))
+matches { .x = 42.0 }.
 </pre></td></tr>
 
 
@@ -1995,9 +2715,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   int a[] = { 1, 2 };
   struct B { int x, y; };
-  B b = { 5, 6 };
-initListExpr()
-  matches "{ 1, 2 }" and "{ 5, 6 }"
+  struct B b = { 5, 6 };
+The matcher initListExpr()
+matches { 1, 2 } and { 5, 6 }
 </pre></td></tr>
 
 
@@ -2006,6 +2726,17 @@ <h2 id="decl-matchers">Node Matchers</h2>
 1, 1L, 0x1 and 1U.
 
 Does not match character-encoded integers such as L'a'.
+
+Given
+  int a = 1;
+  int b = 1L;
+  int c = 0x1;
+  int d = 1U;
+  int e = 1.0;
+
+The matcher integerLiteral() matches
+1, 1L, 0x1 and 1U, but does not match
+1.0.
 </pre></td></tr>
 
 
@@ -2013,18 +2744,26 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="labelStmt0"><pre>Matches label statements.
 
 Given
+void bar();
+void foo() {
   goto FOO;
   FOO: bar();
-labelStmt()
-  matches 'FOO:'
+}
+The matcher labelStmt()
+matches FOO: bar()
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('lambdaExpr0')"><a name="lambdaExpr0Anchor">lambdaExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaExpr.html">LambdaExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="lambdaExpr0"><pre>Matches lambda expressions.
 
-Example matches [&](){return 5;}
-  [&](){return 5;}
+Given
+  void f() {
+    []() { return 5; };
+  }
+
+
+The matcher lambdaExpr() matches []() { return 5; }.
 </pre></td></tr>
 
 
@@ -2035,12 +2774,17 @@ <h2 id="decl-matchers">Node Matchers</h2>
   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();
+  void foo() {
+    T u(f());
+    g(f());
+    f().func();
+    f(); // does not match
+  }
+
+The matcher materializeTemporaryExpr() matches
+f() three times before C++17 and it
+matches f() time with C++17 and later, but
+it does not match the f() in the last line in any version.
 </pre></td></tr>
 
 
@@ -2052,17 +2796,20 @@ <h2 id="decl-matchers">Node Matchers</h2>
     void x() { this->x(); x(); Y y; y.x(); a; this->b; Y::b; }
     int a; static int b;
   };
-memberExpr()
-  matches this->x, x, y.x, a, this->b
+
+The matcher memberExpr()
+matches this->x, x, y.x, a, this->b.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('nullStmt0')"><a name="nullStmt0Anchor">nullStmt</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NullStmt.html">NullStmt</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="nullStmt0"><pre>Matches null statements.
 
+void foo() {
   foo();;
-nullStmt()
-  matches the second ';'
+}
+The matcher nullStmt()
+matches the second ;
 </pre></td></tr>
 
 
@@ -2072,6 +2819,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Example matches @catch
   @try {}
   @catch (...) {}
+
 </pre></td></tr>
 
 
@@ -2081,19 +2829,23 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Example matches @finally
   @try {}
   @finally {}
+
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('objcIvarRefExpr0')"><a name="objcIvarRefExpr0Anchor">objcIvarRefExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCIvarRefExpr.html">ObjCIvarRefExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="objcIvarRefExpr0"><pre>Matches a reference to an ObjCIvar.
 
-Example: matches "a" in "init" method:
+Given
 @implementation A {
   NSString *a;
 }
 - (void) init {
   a = @"hello";
 }
+
+
+The matcher objcIvarRefExpr() matches a.
 </pre></td></tr>
 
 
@@ -2105,6 +2857,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 "initWithString" instance method on the object returned from
 NSString's "alloc". This matcher should match both message sends.
   [[NSString alloc] initWithString:@"Hello"]
+
+
+The matcher objcMessageExpr() matches
+[[NSString alloc] initWithString:@"Hello"]
 </pre></td></tr>
 
 
@@ -2113,6 +2869,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Example matches @"abcd"
   NSString *s = @"abcd";
+
 </pre></td></tr>
 
 
@@ -2120,6 +2877,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="objcThrowStmt0"><pre>Matches Objective-C statements.
 
 Example matches @throw obj;
+
 </pre></td></tr>
 
 
@@ -2129,6 +2887,7 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Example matches @try
   @try {}
   @catch (...) {}
+
 </pre></td></tr>
 
 
@@ -2136,13 +2895,19 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="ompExecutableDirective0"><pre>Matches any ``#pragma omp`` executable directive.
 
 Given
+  void foo() {
+    #pragma omp parallel
+      {}
+    #pragma omp parallel default(none)
+      {
+        #pragma omp taskyield
+      }
+  }
 
-  #pragma omp parallel
-  #pragma omp parallel default(none)
-  #pragma omp taskyield
-
-``ompExecutableDirective()`` matches ``omp parallel``,
-``omp parallel default(none)`` and ``omp taskyield``.
+The matcher ompExecutableDirective()
+matches #pragma omp parallel,
+#pragma omp parallel default(none)
+and #pragma omp taskyield.
 </pre></td></tr>
 
 
@@ -2151,17 +2916,27 @@ <h2 id="decl-matchers">Node Matchers</h2>
 to reference another expressions and can be met
 in BinaryConditionalOperators, for example.
 
-Example matches 'a'
-  (a ?: c) + 42;
+Given
+  int f(int a, int b) {
+    return (a ?: b) + 42;
+  }
+
+
+The matcher opaqueValueExpr() matches a twice,
+once for the check and once for the expression of the true path.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('parenExpr0')"><a name="parenExpr0Anchor">parenExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ParenExpr.html">ParenExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="parenExpr0"><pre>Matches parentheses used in expressions.
 
-Example matches (foo() + 1)
+Given
   int foo() { return 1; }
-  int a = (foo() + 1);
+  int bar() {
+    int a = (foo() + 1);
+  }
+
+The matcher parenExpr() matches (foo() + 1).
 </pre></td></tr>
 
 
@@ -2177,8 +2952,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
       int a = 0, b = 1; int i = (a, b);
     }
   };
-parenListExpr() matches "*this" but NOT matches (a, b) because (a, b)
-has a predefined type and is a ParenExpr, not a ParenListExpr.
+
+The matcher parenListExpr()
+matches (*this),
+but does not match (a, b)
+because (a, b) has a predefined type and is a ParenExpr, not a
+ParenListExpr.
 </pre></td></tr>
 
 
@@ -2186,7 +2965,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="predefinedExpr0"><pre>Matches predefined identifier expressions [C99 6.4.2.2].
 
 Example: Matches __func__
-  printf("%s", __func__);
+  void f() {
+    const char* func_name = __func__;
+  }
+
+The matcher predefinedExpr()
+matches __func__.
 </pre></td></tr>
 
 
@@ -2194,9 +2978,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="returnStmt0"><pre>Matches return statements.
 
 Given
+int foo() {
   return 1;
-returnStmt()
-  matches 'return 1'
+}
+The matcher returnStmt()
+matches return 1
 </pre></td></tr>
 
 
@@ -2204,26 +2990,35 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="stmt0"><pre>Matches statements.
 
 Given
-  { ++a; }
-stmt()
-  matches both the compound statement '{ ++a; }' and '++a'.
+  void foo(int a) { { ++a; } }
+The matcher stmt()
+matches the function body itself { { ++a; } }, the compound
+statement { ++a; }, the expression ++a and a.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('stmtExpr0')"><a name="stmtExpr0Anchor">stmtExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1StmtExpr.html">StmtExpr</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="stmtExpr0"><pre>Matches statement expression (GNU extension).
 
-Example match: ({ int X = 4; X; })
-  int C = ({ int X = 4; X; });
+Given
+  void f() {
+    int C = ({ int X = 4; X; });
+  }
+
+The matcher stmtExpr() matches ({ int X = 4; X; }).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('stringLiteral0')"><a name="stringLiteral0Anchor">stringLiteral</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1StringLiteral.html">StringLiteral</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="stringLiteral0"><pre>Matches string literals (also matches wide string literals).
 
-Example matches "abcd", L"abcd"
+Given
   char *s = "abcd";
   wchar_t *ws = L"abcd";
+
+
+The matcher stringLiteral() matches "abcd" and
+L"abcd".
 </pre></td></tr>
 
 
@@ -2234,8 +3029,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
   template <int N>
   struct A { static const int n = N; };
   struct B : public A<42> {};
-substNonTypeTemplateParmExpr()
-  matches "N" in the right-hand side of "static const int n = N;"
+
+The matcher substNonTypeTemplateParmExpr()
+matches N in the right-hand side of "static const int n = N;"
 </pre></td></tr>
 
 
@@ -2243,9 +3039,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="switchCase0"><pre>Matches case and default statements inside switch statements.
 
 Given
+void foo(int a) {
   switch(a) { case 42: break; default: break; }
-switchCase()
-  matches 'case 42:' and 'default:'.
+}
+The matcher switchCase()
+matches case 42: break and default: break
 </pre></td></tr>
 
 
@@ -2253,9 +3051,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="switchStmt0"><pre>Matches switch statements.
 
 Given
+void foo(int a) {
   switch(a) { case 42: break; default: break; }
-switchStmt()
-  matches 'switch(a)'.
+}
+The matcher switchStmt()
+matches switch(a) { case 42: break; default: break; }.
 </pre></td></tr>
 
 
@@ -2263,10 +3063,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="unaryExprOrTypeTraitExpr0"><pre>Matches sizeof (C99), alignof (C++11) and vec_step (OpenCL)
 
 Given
-  Foo x = bar;
+  int x = 42;
   int y = sizeof(x) + alignof(x);
-unaryExprOrTypeTraitExpr()
-  matches sizeof(x) and alignof(x)
+
+The matcher unaryExprOrTypeTraitExpr()
+matches sizeof(x) and alignof(x)
 </pre></td></tr>
 
 
@@ -2274,7 +3075,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="unaryOperator0"><pre>Matches unary operator expressions.
 
 Example matches !a
-  !a || b
+  void foo(bool a, bool b) {
+    !a || b;
+  }
+
+
+The matcher unaryOperator() matches !a.
 </pre></td></tr>
 
 
@@ -2289,8 +3095,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
   void bar() {
     foo<T>();
   }
-unresolvedLookupExpr()
-  matches foo<T>() </pre></td></tr>
+
+The matcher unresolvedLookupExpr()
+matches foo<T>.
+</pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('unresolvedMemberExpr0')"><a name="unresolvedMemberExpr0Anchor">unresolvedMemberExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UnresolvedMemberExpr.html">UnresolvedMemberExpr</a>>...</td></tr>
@@ -2302,8 +3110,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
     void g();
   };
   template <class T> void h() { X x; x.f<T>(); x.g(); }
-unresolvedMemberExpr()
-  matches x.f<T>
+
+The matcher unresolvedMemberExpr()
+matches x.f<T>
 </pre></td></tr>
 
 
@@ -2311,6 +3120,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="userDefinedLiteral0"><pre>Matches user defined literal operator call.
 
 Example match: "foo"_suffix
+Given
+  float operator ""_foo(long double);
+  float a = 1234.5_foo;
+
+
+The matcher userDefinedLiteral() matches 1234.5_foo.
 </pre></td></tr>
 
 
@@ -2318,9 +3133,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="whileStmt0"><pre>Matches while statements.
 
 Given
+void foo() {
   while (true) {}
-whileStmt()
-  matches 'while (true) {}'.
+}
+
+The matcher whileStmt()
+matches while (true) {}.
 </pre></td></tr>
 
 
@@ -2330,8 +3148,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   template <typename T> struct C {};
   C<int> c;
-templateArgumentLoc()
-  matches 'int' in C<int>.
+
+The matcher templateArgumentLoc()
+matches int in C<int>.
 </pre></td></tr>
 
 
@@ -2341,8 +3160,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   template <typename T> struct C {};
   C<int> c;
-templateArgument()
-  matches 'int' in C<int>.
+
+The matcher
+templateSpecializationType(hasAnyTemplateArgument(templateArgument()))
+matches C<int>.
 </pre></td></tr>
 
 
@@ -2350,10 +3171,14 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="templateName0"><pre>Matches template name.
 
 Given
-  template <typename T> class X { };
-  X<int> xi;
-templateName()
-  matches 'X' in X<int>.
+  template<template <typename> class S> class X {};
+  template<typename T> class Y {};
+  X<Y> xi;
+
+The matcher
+classTemplateSpecializationDecl(hasAnyTemplateArgument(
+              refersToTemplate(templateName())))
+matches the specialization class X<Y>
 </pre></td></tr>
 
 
@@ -2363,8 +3188,8 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   struct s {};
   struct s ss;
-elaboratedTypeLoc()
-  matches the `TypeLoc` of the variable declaration of `ss`.
+The matcher elaboratedTypeLoc()
+matches the type struct s of ss.
 </pre></td></tr>
 
 
@@ -2373,8 +3198,8 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   int* x;
-pointerTypeLoc()
-  matches `int*`.
+The matcher pointerTypeLoc()
+  matches int*.
 </pre></td></tr>
 
 
@@ -2383,8 +3208,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   const int x = 0;
-qualifiedTypeLoc()
-  matches `const int`.
+
+The matcher qualifiedTypeLoc()
+matches the type of the variable declaration x . However, the
+current implementation of QualifiedTypeLoc does not store the source
+locations for the qualifiers of the type int.
 </pre></td></tr>
 
 
@@ -2395,8 +3223,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
   int x = 3;
   int& l = x;
   int&& r = 3;
-referenceTypeLoc()
-  matches `int&` and `int&&`.
+
+
+The matcher referenceTypeLoc()
+  matches int& and int&&.
 </pre></td></tr>
 
 
@@ -2406,13 +3236,25 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   template <typename T> class C {};
   C<char> var;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(typeLoc())))
-  matches `C<char> var`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(typeLoc())))))
+matches C<char> var.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td><td class="name" onclick="toggle('typeLoc0')"><a name="typeLoc0Anchor">typeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="typeLoc0"><pre>Matches TypeLocs in the clang AST.
+
+That is, information about a type and where it was written.
+
+  void foo(int val);
+
+The matcher declaratorDecl(hasTypeLoc(typeLoc().bind("type")))
+matches void foo(int val) and int val, with
+typeLoc() matching void and
+int respectively.
 </pre></td></tr>
 
 
@@ -2423,8 +3265,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
   int a[] = { 2, 3 };
   int b[4];
   void f() { int c[a[0]]; }
-arrayType()
-  matches "int a[]", "int b[4]" and "int c[a[0]]";
+The matcher arrayType()
+int[4], int[a[0]] and
+int[];
 </pre></td></tr>
 
 
@@ -2433,20 +3276,25 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   _Atomic(int) i;
-atomicType()
-  matches "_Atomic(int) i"
+The matcher atomicType()
+_Atomic(int)
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('autoType0')"><a name="autoType0Anchor">autoType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AutoType.html">AutoType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="autoType0"><pre>Matches types nodes representing C++11 auto types.
 
-Given:
-  auto n = 4;
-  int v[] = { 2, 3 }
-  for (auto i : v) { }
-autoType()
-  matches "auto n" and "auto i"
+Given
+  void foo() {
+    auto n = 4;
+    int v[] = { 2, 3 };
+    for (auto i : v) { };
+  }
+
+The matcher autoType()
+matches the auto of n and i ,
+as well as the auto types for the implicitly generated code of the range-for
+loop (for the range, the begin iterator and the end iterator).
 </pre></td></tr>
 
 
@@ -2462,13 +3310,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="builtinType0"><pre>Matches builtin Types.
 
 Given
-  struct A {};
-  A a;
+  enum E { Ok };
+  enum E e;
   int b;
   float c;
-  bool d;
-builtinType()
-  matches "int b", "float c" and "bool d"
+The matcher varDecl(hasType(builtinType()))
+matches int b and float c.
 </pre></td></tr>
 
 
@@ -2477,8 +3324,8 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   _Complex float f;
-complexType()
-  matches "_Complex float f"
+The matcher complexType()
+_Complex float
 </pre></td></tr>
 
 
@@ -2486,37 +3333,38 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="constantArrayType0"><pre>Matches C arrays with a specified constant size.
 
 Given
-  void() {
+  void foo() {
     int a[2];
     int b[] = { 2, 3 };
     int c[b[0]];
   }
-constantArrayType()
-  matches "int a[2]"
+The matcher constantArrayType()
+int[2]
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('decayedType0')"><a name="decayedType0Anchor">decayedType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DecayedType.html">DecayedType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="decayedType0"><pre>Matches decayed type
-Example matches i[] in declaration of f.
-    (matcher = valueDecl(hasType(decayedType(hasDecayedType(pointerType())))))
-Example matches i[1].
-    (matcher = expr(hasType(decayedType(hasDecayedType(pointerType())))))
   void f(int i[]) {
     i[1] = 0;
   }
-</pre></td></tr>
+The matcher
+valueDecl(hasType(decayedType(hasDecayedType(pointerType()))))
+matches int i[] in declaration of The matcher
+expr(hasType(decayedType(hasDecayedType(pointerType()))))
+matches i in </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('decltypeType0')"><a name="decltypeType0Anchor">decltypeType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DecltypeType.html">DecltypeType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="decltypeType0"><pre>Matches types nodes representing C++11 decltype(<expr>) types.
 
-Given:
+Given
   short i = 1;
   int j = 42;
   decltype(i + j) result = i + j;
-decltypeType()
-  matches "decltype(i + j)"
+
+The matcher decltypeType()
+decltype(i + j)
 </pre></td></tr>
 
 
@@ -2529,8 +3377,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
   class C { public: C(T); };
 
   C c(123);
-deducedTemplateSpecializationType() matches the type in the declaration
-of the variable c.
+
+The matcher deducedTemplateSpecializationType() matches the type
+C of the declaration of the variable c.
 </pre></td></tr>
 
 
@@ -2542,8 +3391,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
   class array {
     T data[Size];
   };
-dependentSizedArrayType()
-  matches "T data[Size]"
+
+The matcher dependentSizedArrayType()
+T[Size]
 </pre></td></tr>
 
 
@@ -2556,8 +3406,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
   class vector {
     typedef T __attribute__((ext_vector_type(Size))) type;
   };
-dependentSizedExtVectorType()
-  matches "T __attribute__((ext_vector_type(Size)))"
+
+The matcher dependentSizedExtVectorType()
+T __attribute__((ext_vector_type(Size)))
 </pre></td></tr>
 
 
@@ -2573,11 +3424,17 @@ <h2 id="decl-matchers">Node Matchers</h2>
   }
   class C {};
 
-  class C c;
+  C c;
   N::M::D d;
 
-elaboratedType() matches the type of the variable declarations of both
-c and d.
+
+The matcher elaboratedType() matches the type
+C three times. Once for the type of the
+variable c, once for the type of the class definition and once for the
+type in the injected class name. For D}, it matches
+N::M::D of variable d and its class definition and
+injected class name
+D one time respectively.
 </pre></td></tr>
 
 
@@ -2591,8 +3448,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
   C c;
   S s;
 
-enumType() matches the type of the variable declarations of both c and
-s.
+
+The matcher enumType() matches the type
+enum C of c ,
+and the type enum S of s .
 </pre></td></tr>
 
 
@@ -2602,9 +3461,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   int (*f)(int);
   void g();
-functionProtoType()
-  matches "int (*f)(int)" and the type of "g" in C++ mode.
-  In C mode, "g" is not matched because it does not contain a prototype.
+The matcher functionProtoType()
+matches the type int (int) of 'f' and the type
+void (void) of 'g' in C++ mode.
+In C, the type void () of 'g' is not
+matched because it does not contain a prototype.
 </pre></td></tr>
 
 
@@ -2614,8 +3475,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   int (*f)(int);
   void g();
-functionType()
-  matches "int (*f)(int)" and the type of "g".
+The matcher functionType()
+int (int) and the type of
+void (void) in C++ and in C23 and
+later. Before C23, the function type for f will be matched the same way,
+but the function type for g will match
+void ().
 </pre></td></tr>
 
 
@@ -2626,27 +3491,30 @@ <h2 id="decl-matchers">Node Matchers</h2>
   int a[] = { 2, 3 };
   int b[42];
   void f(int c[]) { int d[a[0]]; };
-incompleteArrayType()
-  matches "int a[]" and "int c[]"
+The matcher incompleteArrayType()
+int[] and int[]
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('injectedClassNameType0')"><a name="injectedClassNameType0Anchor">injectedClassNameType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="injectedClassNameType0"><pre>Matches injected class name types.
 
-Example matches S s, but not S<T> s.
-    (matcher = parmVarDecl(hasType(injectedClassNameType())))
+Given
   template <typename T> struct S {
     void f(S s);
     void g(S<T> s);
   };
+
+The matcher
+parmVarDecl(hasType(elaboratedType(namesType(injectedClassNameType()))))
+matches S s, but not s}
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('lValueReferenceType0')"><a name="lValueReferenceType0Anchor">lValueReferenceType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1LValueReferenceType.html">LValueReferenceType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="lValueReferenceType0"><pre>Matches lvalue reference types.
 
-Given:
+Given
   int *a;
   int &b = *a;
   int &&c = 1;
@@ -2655,8 +3523,11 @@ <h2 id="decl-matchers">Node Matchers</h2>
   auto &&f = 2;
   int g = 5;
 
-lValueReferenceType() matches the types of b, d, and e. e is
-matched since the type is deduced as int& by reference collapsing rules.
+
+The matcher lValueReferenceType() matches the type
+int & of b and the type auto &
+of d.
+FIXME: figure out why auto changechange matches twice
 </pre></td></tr>
 
 
@@ -2667,18 +3538,23 @@ <h2 id="decl-matchers">Node Matchers</h2>
   #define CDECL __attribute__((cdecl))
   typedef void (CDECL *X)();
   typedef void (__attribute__((cdecl)) *Y)();
-macroQualifiedType()
-  matches the type of the typedef declaration of X but not Y.
+The matcher macroQualifiedType()
+matches the type CDECL void
+(void) of the typedef declaration of X , unless when in C98-C17, there
+CDECL void (),
+but it does not match the type
+__attribute((cdecl)) void () of Y .
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('memberPointerType0')"><a name="memberPointerType0Anchor">memberPointerType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="memberPointerType0"><pre>Matches member pointer types.
 Given
-  struct A { int i; }
-  A::* ptr = A::i;
-memberPointerType()
-  matches "A::* ptr"
+  struct A { int i; };
+  int A::* ptr = &A::i;
+
+The matcher memberPointerType()
+matches int struct A::*.
 </pre></td></tr>
 
 
@@ -2692,8 +3568,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
   @interface Foo
   @end
   Foo *f;
-pointerType()
-  matches "Foo *f", but does not match "int *a".
+
+The matcher pointerType()
+matches Foo *, but does not match
+int *.
 </pre></td></tr>
 
 
@@ -2704,8 +3582,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
   int (*ptr_to_array)[4];
   int *array_of_ptrs[4];
 
-varDecl(hasType(pointsTo(parenType()))) matches ptr_to_array but not
-array_of_ptrs.
+The matcher varDecl(hasType(pointsTo(parenType())))
+  matches ptr_to_array but not
+  array_of_ptrs.
 </pre></td></tr>
 
 
@@ -2714,22 +3593,28 @@ <h2 id="decl-matchers">Node Matchers</h2>
 types.
 
 Given
-  int *a;
-  int &b = *a;
-  int c = 5;
+  typedef int* int_ptr;
+  void foo(char *str,
+           int val,
+           int *val_ptr,
+           int_ptr not_a_ptr,
+           int_ptr *ptr);
+
+The matcher parmVarDecl(hasType(pointerType()))
+matches char *str, int *val_ptr and
+int_ptr *ptr.
 
   @interface Foo
   @end
   Foo *f;
-pointerType()
-  matches "int *a", but does not match "Foo *f".
+
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('rValueReferenceType0')"><a name="rValueReferenceType0Anchor">rValueReferenceType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1RValueReferenceType.html">RValueReferenceType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="rValueReferenceType0"><pre>Matches rvalue reference types.
 
-Given:
+Given
   int *a;
   int &b = *a;
   int &&c = 1;
@@ -2738,8 +3623,10 @@ <h2 id="decl-matchers">Node Matchers</h2>
   auto &&f = 2;
   int g = 5;
 
-rValueReferenceType() matches the types of c and f. e is not
-matched as it is deduced to int& by reference collapsing rules.
+
+The matcher rValueReferenceType() matches the type
+int && of c and the type
+auto && of f.
 </pre></td></tr>
 
 
@@ -2753,8 +3640,14 @@ <h2 id="decl-matchers">Node Matchers</h2>
   C c;
   S s;
 
-recordType() matches the type of the variable declarations of both c
-and s.
+
+The matcher recordType() matches the type
+class C of the variable declaration of c and
+matches the type struct S of the variable
+declaration of s.
+Both of these types are matched three times, once for the type of the
+variable, once for the definition of the class, and once for the type of the
+injected class name.
 </pre></td></tr>
 
 
@@ -2770,7 +3663,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
   auto &&f = 2;
   int g = 5;
 
-referenceType() matches the types of b, c, d, e, and f.
+
+The matcher referenceType() matches the type
+int & of b , the type int && of
+c, the type
+auto & d, and the type
+auto && of e and f.
 </pre></td></tr>
 
 
@@ -2781,10 +3679,17 @@ <h2 id="decl-matchers">Node Matchers</h2>
 Given
   template <typename T>
   void F(T t) {
+    T local;
     int i = 1 + t;
   }
+  void f() {
+    F(0);
+  }
 
-substTemplateTypeParmType() matches the type of 't' but not '1'
+
+The matcher varDecl(hasType(substTemplateTypeParmType()))
+matches T t and T local for the substituted template type
+int in the instantiation of F .
 </pre></td></tr>
 
 
@@ -2792,14 +3697,18 @@ <h2 id="decl-matchers">Node Matchers</h2>
 <tr><td colspan="4" class="doc" id="tagType0"><pre>Matches tag types (record and enum types).
 
 Given
-  enum E {};
+  enum E { Ok };
   class C {};
 
   E e;
   C c;
 
-tagType() matches the type of the variable declarations of both e
-and c.
+
+The matcher tagType() matches the type
+enum E of variable e and the type
+class C three times, once for the type
+of the variable c , once for the type of the class definition and once of
+the type in the injected class name.
 </pre></td></tr>
 
 
@@ -2810,25 +3719,38 @@ <h2 id="decl-matchers">Node Matchers</h2>
   template <typename T>
   class C { };
 
-  template class C<int>;  // A
-  C<char> var;            // B
+  template class C<int>;
+  C<int> intvar;
+  C<char> charvar;
 
-templateSpecializationType() matches the type of the explicit
-instantiation in A and the type of the variable declaration in B.
+
+The matcher templateSpecializationType() matches the type
+C<int> of the explicit instantiation in A and the
+type C<char> of the variable declaration in
+B.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('templateTypeParmType0')"><a name="templateTypeParmType0Anchor">templateTypeParmType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="templateTypeParmType0"><pre>Matches template type parameter types.
 
-Example matches T, but not int.
-    (matcher = templateTypeParmType())
+Given
   template <typename T> void f(int i);
+
+The matcher templateTypeParmType() matches T,
+but does not match int.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('type0')"><a name="type0Anchor">type</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="type0"><pre>Matches Types in the clang AST.
+
+Given
+  const int b = 1;
+
+The matcher varDecl(hasType(type().bind("type")))
+matches const int b = 1, with type()
+matching int.
 </pre></td></tr>
 
 
@@ -2837,18 +3759,22 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   typedef int X;
-typedefType()
-  matches "typedef int X"
+  X x = 0;
+The matcher typedefType()
+matches X.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('unaryTransformType0')"><a name="unaryTransformType0Anchor">unaryTransformType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UnaryTransformType.html">UnaryTransformType</a>>...</td></tr>
 <tr><td colspan="4" class="doc" id="unaryTransformType0"><pre>Matches types nodes representing unary type transformations.
 
-Given:
-  typedef __underlying_type(T) type;
-unaryTransformType()
-  matches "__underlying_type(T)"
+Given
+  template <typename T> struct A {
+    typedef __underlying_type(T) type;
+  };
+
+The matcher unaryTransformType()
+matches __underlying_type(T)
 </pre></td></tr>
 
 
@@ -2860,7 +3786,9 @@ <h2 id="decl-matchers">Node Matchers</h2>
   using a::S;
   S s;
 
-usingType() matches the type of the variable declaration of s.
+
+The matcher usingType() matches the type a::S
+of the variable declaration of s.
 </pre></td></tr>
 
 
@@ -2870,12 +3798,12 @@ <h2 id="decl-matchers">Node Matchers</h2>
 
 Given
   void f() {
-    int a[] = { 2, 3 }
+    int a[] = { 2, 3 };
     int b[42];
     int c[a[0]];
   }
-variableArrayType()
-  matches "int c[a[0]]"
+The matcher variableArrayType()
+int[a[0]]
 </pre></td></tr>
 
 <!--END_DECL_MATCHERS -->
@@ -2899,6 +3827,12 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="allOf0"><pre>Matches if all given matchers match.
 
 Usable as: Any Matcher
+
+  int v0 = 0;
+  int v1 = 1;
+
+The matcher varDecl(allOf(hasName("v0"), hasType(isInteger())))
+matches int v0 = 0.
 </pre></td></tr>
 
 
@@ -2906,6 +3840,13 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="anyOf0"><pre>Matches if any of the given matchers matches.
 
 Usable as: Any Matcher
+
+  char v0 = 'a';
+  int v1 = 1;
+  float v2 = 2.0;
+
+The matcher varDecl(anyOf(hasName("v0"), hasType(isInteger())))
+matches char v0 = 'a' and int v1 = 1.
 </pre></td></tr>
 
 
@@ -2916,11 +3857,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 additional constraint. This will often be used with an explicit conversion
 to an internal::Matcher<> type such as TypeMatcher.
 
-Example: DeclarationMatcher(anything()) matches all declarations, e.g.,
-"int* p" and "void f()" in
+Given
   int* p;
   void f();
-
+The matcher decl(anything())
+matches int* p and void f().
 Usable as: Any Matcher
 </pre></td></tr>
 
@@ -2929,21 +3870,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="mapAnyOf0"><pre>Matches any of the NodeMatchers with InnerMatchers nested within
 
 Given
-  if (true);
-  for (; true; );
-with the matcher
-  mapAnyOf(ifStmt, forStmt).with(
-    hasCondition(cxxBoolLiteralExpr(equals(true)))
-    ).bind("trueCond")
-matches the if and the for. It is equivalent to:
-  auto trueCond = hasCondition(cxxBoolLiteralExpr(equals(true)));
-  anyOf(
-    ifStmt(trueCond).bind("trueCond"),
-    forStmt(trueCond).bind("trueCond")
-    );
+  void f() {
+    if (true);
+    for (; true; );
+  }
+
+
+The matcher stmt(mapAnyOf(ifStmt, forStmt).with(
+    hasCondition(cxxBoolLiteral(equals(true)))
+    )),
+which is equivalent to
+stmt(anyOf(
+    ifStmt(hasCondition(cxxBoolLiteral(equals(true)))).bind("trueCond"),
+    forStmt(hasCondition(cxxBoolLiteral(equals(true)))).bind("trueCond")
+    )),
+matches if (true); and for (; true; );.
 
 The with() chain-call accepts zero or more matchers which are combined
 as-if with allOf() in each of the node matchers.
+
 Usable as: Any Matcher
 </pre></td></tr>
 
@@ -2951,10 +3896,13 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<*></td><td class="name" onclick="toggle('unless0')"><a name="unless0Anchor">unless</a></td><td>Matcher<*></td></tr>
 <tr><td colspan="4" class="doc" id="unless0"><pre>Matches if the provided matcher does not match.
 
-Example matches Y (matcher = cxxRecordDecl(unless(hasName("X"))))
+Given
   class X {};
   class Y {};
 
+The matcher cxxRecordDecl(unless(hasName("X")))
+matches Y
+
 Usable as: Any Matcher
 </pre></td></tr>
 
@@ -2962,6 +3910,20 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Attr.html">Attr</a>></td><td class="name" onclick="toggle('isImplicit1')"><a name="isImplicit1Anchor">isImplicit</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isImplicit1"><pre>Matches an entity that has been implicitly added by the compiler (e.g.
 implicit default/copy constructors).
+
+Given
+  struct S {};
+  void f(S obj) {
+    S copy = obj;
+    [&](){ return copy; };
+  }
+
+
+The matcher cxxConstructorDecl(isImplicit(), isCopyConstructor())
+matches the implicit copy constructor of S.
+The matcher lambdaExpr(forEachLambdaCapture(
+    lambdaCapture(isImplicit()))) matches [&](){ return copy; },
+because it implicitly captures copy .
 </pre></td></tr>
 
 
@@ -2969,9 +3931,26 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasAnyOperatorName0"><pre>Matches operator expressions (binary or unary) that have any of the
 specified names.
 
-   hasAnyOperatorName("+", "-")
- Is equivalent to
-   anyOf(hasOperatorName("+"), hasOperatorName("-"))
+It provides a compact way of writing if an operator has any of the specified
+names:
+The matcher
+   hasAnyOperatorName("+", "-")
+Is equivalent to
+   hasOperatorName("-"))}
+
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+void bar(bool a, bool b) {
+  a && b;
+ }
+
+The matcher binaryOperator(hasAnyOperatorName("||", "&&"))
+matches a || b and a && b.
+The matcher unaryOperator(hasAnyOperatorName("-", "!"))
+matches !(a || b).
 </pre></td></tr>
 
 
@@ -2979,43 +3958,62 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperatorName0"><pre>Matches the operator Name of operator expressions and fold expressions
 (binary or unary).
 
-Example matches a || b (matcher = binaryOperator(hasOperatorName("||")))
-  !(a || b)
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+The matcher binaryOperator(hasOperatorName("||"))
+matches a || b
 
-Example matches `(0 + ... + args)`
-    (matcher = cxxFoldExpr(hasOperatorName("+")))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
   }
+
+The matcher cxxFoldExpr(hasOperatorName("+"))
+ matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('isAssignmentOperator0')"><a name="isAssignmentOperator0Anchor">isAssignmentOperator</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isAssignmentOperator0"><pre>Matches all kinds of assignment operators.
 
-Example 1: matches a += b (matcher = binaryOperator(isAssignmentOperator()))
+Given
+void foo(int a, int b) {
   if (a == b)
     a += b;
+}
+The matcher binaryOperator(isAssignmentOperator())
+matches a += b.
 
-Example 2: matches s1 = s2
-           (matcher = cxxOperatorCallExpr(isAssignmentOperator()))
+Given
   struct S { S& operator=(const S&); };
   void x() { S s1, s2; s1 = s2; }
+
+The matcher cxxOperatorCallExpr(isAssignmentOperator())
+matches s1 = s2.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('isComparisonOperator0')"><a name="isComparisonOperator0Anchor">isComparisonOperator</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isComparisonOperator0"><pre>Matches comparison operators.
 
-Example 1: matches a == b (matcher = binaryOperator(isComparisonOperator()))
+Given
+void foo(int a, int b) {
   if (a == b)
     a += b;
+}
+The matcher binaryOperator(isComparisonOperator())
+matches a == b
 
-Example 2: matches s1 < s2
-           (matcher = cxxOperatorCallExpr(isComparisonOperator()))
+Given
   struct S { bool operator<(const S& other); };
   void x(S s1, S s2) { bool b1 = s1 < s2; }
+
+The matcher cxxOperatorCallExpr(isComparisonOperator())
+matches s1 < s2
 </pre></td></tr>
 
 
@@ -3023,16 +4021,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isPrivate1"><pre>Matches private C++ declarations and C++ base specifers that specify private
 inheritance.
 
-Examples:
+Given
   class C {
   public:    int a;
   protected: int b;
-  private:   int c; // fieldDecl(isPrivate()) matches 'c'
+  private:   int c;
   };
 
+The matcher fieldDecl(isPrivate())
+matches c.
+
   struct Base {};
-  struct Derived1 : private Base {}; // matches 'Base'
-  class Derived2 : Base {}; // matches 'Base'
+  struct Derived1 : private Base {}; // Base
+  class Derived2 : Base {}; // Base
+
+The matcher
+cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isPrivate()).bind("base")))
+matches Derived1 and Derived2, with
+cxxBaseSpecifier(isPrivate()) matching
+Base.
 </pre></td></tr>
 
 
@@ -3040,15 +4047,24 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isProtected1"><pre>Matches protected C++ declarations and C++ base specifers that specify
 protected inheritance.
 
-Examples:
+Given
   class C {
   public:    int a;
-  protected: int b; // fieldDecl(isProtected()) matches 'b'
+  protected: int b;
   private:   int c;
   };
 
+The matcher fieldDecl(isProtected())
+matches b.
+
   class Base {};
-  class Derived : protected Base {}; // matches 'Base'
+  class Derived : protected Base {};
+
+The matcher
+cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isProtected()).bind("base")))
+matches Derived, with
+cxxBaseSpecifier(isProtected()) matching
+Base.
 </pre></td></tr>
 
 
@@ -3056,16 +4072,26 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isPublic1"><pre>Matches public C++ declarations and C++ base specifers that specify public
 inheritance.
 
-Examples:
+Given
   class C {
-  public:    int a; // fieldDecl(isPublic()) matches 'a'
+  public:    int a;
   protected: int b;
   private:   int c;
   };
 
+The matcher fieldDecl(isPublic())
+matches a.
+
+Given
   class Base {};
-  class Derived1 : public Base {}; // matches 'Base'
-  struct Derived2 : Base {}; // matches 'Base'
+  class Derived1 : public Base {};
+  struct Derived2 : Base {};
+
+The matcher
+cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isPublic()).bind("base")))
+matches Derived1 and Derived2,
+with cxxBaseSpecifier(isPublic()) matching
+public Base and Base.
 </pre></td></tr>
 
 
@@ -3073,16 +4099,23 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isVirtual1"><pre>Matches declarations of virtual methods and C++ base specifers that specify
 virtual inheritance.
 
-Example:
+Given
   class A {
    public:
     virtual void x(); // matches x
   };
 
-Example:
-  class Base {};
-  class DirectlyDerived : virtual Base {}; // matches Base
-  class IndirectlyDerived : DirectlyDerived, Base {}; // matches Base
+The matcher cxxMethodDecl(isVirtual())
+matches x.
+
+Given
+  struct Base {};
+  struct DirectlyDerived : virtual Base {}; // matches Base
+  struct IndirectlyDerived : DirectlyDerived, Base {}; // matches Base
+
+The matcher
+cxxRecordDecl(hasDirectBase(cxxBaseSpecifier(isVirtual())))
+matches DirectlyDerived.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>
 </pre></td></tr>
@@ -3096,22 +4129,27 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="equals2"><pre>Matches literals that are equal to the given value of type ValueT.
 
 Given
+void f(char, bool, double, int);
+void foo() {
   f('false, 3.14, 42);
-characterLiteral(equals(0))
-  matches 'cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
-  match false
-floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
-  match 3.14
-integerLiteral(equals(42))
-  matches 42
+}
+
+The matcher characterLiteral(equals(0U)) matches 'The matchers cxxBoolLiteral(equals(false)) and
+cxxBoolLiteral(equals(0)) match false.
+The matcher floatLiteral(equals(3.14)) matches 3.14.
+The matcher integerLiteral(equals(42)) matches 42.
 
 Note that you cannot directly match a negative numeric literal because the
 minus sign is not part of the literal: It is a unary operator whose operand
 is the positive numeric literal. Instead, you must use a unaryOperator()
 matcher to match the minus sign:
 
-unaryOperator(hasOperatorName("-"),
-              hasUnaryOperand(integerLiteral(equals(13))))
+Given
+  int val = -1;
+
+The matcher unaryOperator(hasOperatorName("-"),
+              hasUnaryOperand(integerLiteral(equals(1))))
+matches -1.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>>,
            Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>
@@ -3130,14 +4168,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isCatchAll0"><pre>Matches a C++ catch statement that has a catch-all handler.
 
 Given
-  try {
-    // ...
-  } catch (int) {
-    // ...
-  } catch (...) {
-    // ...
+  void foo() {
+    try {}
+    catch (int) {}
+    catch (...) {}
   }
-cxxCatchStmt(isCatchAll()) matches catch(...) but not catch(int).
+
+The matcher cxxCatchStmt(isCatchAll())
+matches catch (...) {}
+but does not match catch(int)
 </pre></td></tr>
 
 
@@ -3145,12 +4184,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="argumentCountAtLeast1"><pre>Checks that a call expression or a constructor call expression has at least
 the specified number of arguments (including absent default arguments).
 
-Example matches f(0, 0) and g(0, 0, 0)
-(matcher = callExpr(argumentCountAtLeast(2)))
+Given
   void f(int x, int y);
   void g(int x, int y, int z);
-  f(0, 0);
-  g(0, 0, 0);
+  void foo() {
+    f(0, 0);
+    g(0, 0, 0);
+  }
+The matcher callExpr(argumentCountAtLeast(2))
+matches f(0, 0) and g(0, 0, 0)
 </pre></td></tr>
 
 
@@ -3158,14 +4200,39 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="argumentCountIs1"><pre>Checks that a call expression or a constructor call expression has
 a specific number of arguments (including absent default arguments).
 
-Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2)))
+Given
   void f(int x, int y);
-  f(0, 0);
+  void foo() {
+    f(0, 0);
+  }
+The matcher callExpr(argumentCountIs(2))
+matches f(0, 0)
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('isListInitialization0')"><a name="isListInitialization0Anchor">isListInitialization</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isListInitialization0"><pre>Matches a constructor call expression which uses list initialization.
+
+Given
+  namespace std {
+    template <typename T>
+    class initializer_list {
+      const T* begin;
+      const T* end;
+    };
+  }
+  template <typename T> class vector {
+    public: vector(std::initializer_list<T>) {}
+  };
+
+  vector<int> a({ 1, 2, 3 });
+  vector<int> b = { 4, 5 };
+  int c[] = { 6, 7 };
+  struct pair { int x; int y; };
+  pair d = { 8, 9 };
+
+The matcher cxxConstructExpr(isListInitialization())
+matches { 4, 5 }.
 </pre></td></tr>
 
 
@@ -3175,11 +4242,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
 void foo() {
-  struct point { double x; double y; };
-  point pt[2] = { { 1.0, 2.0 } };
+  struct Foo {
+    double x;
+  };
+  auto Val = Foo();
 }
-initListExpr(has(cxxConstructExpr(requiresZeroInitialization()))
-will match the implicit array filler for pt[1].
+
+The matcher
+cxxConstructExpr(requiresZeroInitialization())
+matches Foo() because the x member has to be zero initialized.
 </pre></td></tr>
 
 
@@ -3192,7 +4263,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     S(const S &); // #2
     S(S &&); // #3
   };
-cxxConstructorDecl(isCopyConstructor()) will match #2, but not #1 or #3.
+
+The matcher cxxConstructorDecl(isCopyConstructor())
+matches S(const S &),
+but does not match S() or S(S &&).
 </pre></td></tr>
 
 
@@ -3205,7 +4279,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     S(const S &); // #2
     S(S &&); // #3
   };
-cxxConstructorDecl(isDefaultConstructor()) will match #1, but not #2 or #3.
+
+The matcher cxxConstructorDecl(isDefaultConstructor())
+matches S()
+but does not match S(const S &); or S(S &&);.
 </pre></td></tr>
 
 
@@ -3219,8 +4296,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     S(S &&) : S() {} // #3
   };
   S::S() : S(0) {} // #4
-cxxConstructorDecl(isDelegatingConstructor()) will match #3 and #4, but not
-#1 or #2.
+
+The matcher cxxConstructorDecl(isDelegatingConstructor())
+matches S(S &&) : S() {} and S::S() : S(0) {},
+but does not match S() or S(int).
 </pre></td></tr>
 
 
@@ -3236,15 +4315,27 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     explicit S(double); // #2
     operator int(); // #3
     explicit operator bool(); // #4
-    explicit(false) S(bool) // # 7
-    explicit(true) S(char) // # 8
-    explicit(b) S(S) // # 9
+    explicit(false) S(bool); // # 7
+    explicit(true) S(char); // # 8
+    explicit(b) S(float); // # 9
   };
-  S(int) -> S<true> // #5
-  explicit S(double) -> S<false> // #6
-cxxConstructorDecl(isExplicit()) will match #2 and #8, but not #1, #7 or #9.
-cxxConversionDecl(isExplicit()) will match #4, but not #3.
-cxxDeductionGuideDecl(isExplicit()) will match #6, but not #5.
+  S(int) -> S<true>; // #5
+  explicit S(double) -> S<false>; // #6
+
+The matcher cxxConstructorDecl(isExplicit())
+matches explicit S(double)
+and explicit(true) S(char)
+but does not match S(int);, explicit(false) S(bool); or
+explicit(b) S(float)
+The matcher cxxConversionDecl(isExplicit())
+matches explicit operator bool()
+but does not match operator int().
+The matcher cxxDeductionGuideDecl(isExplicit())
+matches the deduction guide explicit S(double) -> S<false>,
+the implicit copy deduction candiate
+auto (double) -> S<b> and
+the implicitly generated deduction guide for explicit(true) S(char),
+but does not match S(int) -> S<true>.
 </pre></td></tr>
 
 
@@ -3261,7 +4352,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     S(const S &); // #2
     S(S &&); // #3
   };
-cxxConstructorDecl(isMoveConstructor()) will match #3, but not #1 or #2.
+
+The matcher cxxConstructorDecl(isMoveConstructor())
+matches S(S &&)
+but does not match S(); or S(S &&);
 </pre></td></tr>
 
 
@@ -3277,15 +4371,27 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     explicit S(double); // #2
     operator int(); // #3
     explicit operator bool(); // #4
-    explicit(false) S(bool) // # 7
-    explicit(true) S(char) // # 8
-    explicit(b) S(S) // # 9
+    explicit(false) S(bool); // # 7
+    explicit(true) S(char); // # 8
+    explicit(b) S(float); // # 9
   };
-  S(int) -> S<true> // #5
-  explicit S(double) -> S<false> // #6
-cxxConstructorDecl(isExplicit()) will match #2 and #8, but not #1, #7 or #9.
-cxxConversionDecl(isExplicit()) will match #4, but not #3.
-cxxDeductionGuideDecl(isExplicit()) will match #6, but not #5.
+  S(int) -> S<true>; // #5
+  explicit S(double) -> S<false>; // #6
+
+The matcher cxxConstructorDecl(isExplicit())
+matches explicit S(double)
+and explicit(true) S(char)
+but does not match S(int);, explicit(false) S(bool); or
+explicit(b) S(float)
+The matcher cxxConversionDecl(isExplicit())
+matches explicit operator bool()
+but does not match operator int().
+The matcher cxxDeductionGuideDecl(isExplicit())
+matches the deduction guide explicit S(double) -> S<false>,
+the implicit copy deduction candiate
+auto (double) -> S<b> and
+the implicitly generated deduction guide for explicit(true) S(char),
+but does not match S(int) -> S<true>.
 </pre></td></tr>
 
 
@@ -3302,8 +4408,12 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   struct E : B {
     E() : B() {}
   };
+
+The matcher
 cxxConstructorDecl(hasAnyConstructorInitializer(isBaseInitializer()))
-  will match E(), but not match D(int).
+matches E() : B() {} and D(int i) : I(i) {}.
+The constructor of D is matched, because it implicitly has a constructor
+initializer for B .
 </pre></td></tr>
 
 
@@ -3320,8 +4430,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   struct E : B {
     E() : B() {}
   };
+
+The matcher
 cxxConstructorDecl(hasAnyConstructorInitializer(isMemberInitializer()))
-  will match D(int), but not match E().
+  will match D(int i) : I(i) {}, but not match E() : B()
+  {}.
 </pre></td></tr>
 
 
@@ -3330,13 +4443,16 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 code (as opposed to implicitly added by the compiler).
 
 Given
+  struct Bar { explicit Bar(const char*); };
   struct Foo {
     Foo() { }
     Foo(int) : foo_("A") { }
-    string foo_;
+    Bar foo_{""};
   };
-cxxConstructorDecl(hasAnyConstructorInitializer(isWritten()))
-  will match Foo(int), but not Foo()
+
+The matcher
+cxxConstructorDecl(hasAnyConstructorInitializer(isWritten())) will
+match Foo(int) : foo_("A") { }, but not Foo() { }
 </pre></td></tr>
 
 
@@ -3352,15 +4468,27 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     explicit S(double); // #2
     operator int(); // #3
     explicit operator bool(); // #4
-    explicit(false) S(bool) // # 7
-    explicit(true) S(char) // # 8
-    explicit(b) S(S) // # 9
+    explicit(false) S(bool); // # 7
+    explicit(true) S(char); // # 8
+    explicit(b) S(float); // # 9
   };
-  S(int) -> S<true> // #5
-  explicit S(double) -> S<false> // #6
-cxxConstructorDecl(isExplicit()) will match #2 and #8, but not #1, #7 or #9.
-cxxConversionDecl(isExplicit()) will match #4, but not #3.
-cxxDeductionGuideDecl(isExplicit()) will match #6, but not #5.
+  S(int) -> S<true>; // #5
+  explicit S(double) -> S<false>; // #6
+
+The matcher cxxConstructorDecl(isExplicit())
+matches explicit S(double)
+and explicit(true) S(char)
+but does not match S(int);, explicit(false) S(bool); or
+explicit(b) S(float)
+The matcher cxxConversionDecl(isExplicit())
+matches explicit operator bool()
+but does not match operator int().
+The matcher cxxDeductionGuideDecl(isExplicit())
+matches the deduction guide explicit S(double) -> S<false>,
+the implicit copy deduction candiate
+auto (double) -> S<b> and
+the implicitly generated deduction guide for explicit(true) S(char),
+but does not match S(int) -> S<true>.
 </pre></td></tr>
 
 
@@ -3382,7 +4510,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
       S<T> s;
       s.mem();
   }
-cxxDependentScopeMemberExpr(hasMemberName("mem")) matches `s.mem()`
+
+The matcher cxxDependentScopeMemberExpr(hasMemberName("mem"))
+matches s.mem.
 </pre></td></tr>
 
 
@@ -3401,14 +4531,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   };
   template <class T>
   class Z {
-    void x() { this->m; }
+    void x() {
+      this->m;
+      this->t;
+      this->t->m;
+    }
+    int m;
+    T* t;
   };
-memberExpr(isArrow())
-  matches this->x, x, y.x, a, this->b
-cxxDependentScopeMemberExpr(isArrow())
-  matches this->m
-unresolvedMemberExpr(isArrow())
-  matches this->f<T>, f<T>
+
+The matcher memberExpr(isArrow())
+matches this->x, x, a,
+this->b, this->m and two times this->t,
+once for the standalone member expression, and once for the member
+expression that later accesses m .
+Additionally, it does not match this->t->t.
+The matcher cxxDependentScopeMemberExpr(isArrow())
+matches this->t->m, but not this->m or this->t.
+The matcher unresolvedMemberExpr(isArrow())
+matches this->f<T>, f<T>
 </pre></td></tr>
 
 
@@ -3432,19 +4573,20 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
       S<T> s;
       s.mem();
   }
-The matcher
- at code
-cxxDependentScopeMemberExpr(
-  hasObjectExpression(declRefExpr(hasType(templateSpecializationType(
+
+The matcher cxxDependentScopeMemberExpr(
+  hasObjectExpression(declRefExpr(hasType(
+    elaboratedType(namesType(templateSpecializationType(
       hasDeclaration(classTemplateDecl(has(cxxRecordDecl(has(
           cxxMethodDecl(hasName("mem")).bind("templMem")
           )))))
-      )))),
+    )))
+  ))),
   memberHasSameNameAsBoundNode("templMem")
-  )
- at endcode
-first matches and binds the @c mem member of the @c S template, then
-compares its name to the usage in @c s.mem() in the @c x function template
+)
+matches s.mem, with the inner matcher
+cxxMethodDecl(hasName("mem")) matching
+void mem() of the S template.
 </pre></td></tr>
 
 
@@ -3452,23 +4594,29 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperatorName3"><pre>Matches the operator Name of operator expressions and fold expressions
 (binary or unary).
 
-Example matches a || b (matcher = binaryOperator(hasOperatorName("||")))
-  !(a || b)
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+The matcher binaryOperator(hasOperatorName("||"))
+matches a || b
 
-Example matches `(0 + ... + args)`
-    (matcher = cxxFoldExpr(hasOperatorName("+")))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
   }
+
+The matcher cxxFoldExpr(hasOperatorName("+"))
+ matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>></td><td class="name" onclick="toggle('isBinaryFold0')"><a name="isBinaryFold0Anchor">isBinaryFold</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isBinaryFold0"><pre>Matches binary fold expressions, i.e. fold expressions with an initializer.
 
-Example matches `(0 + ... + args)`
-    (matcher = cxxFoldExpr(isBinaryFold()))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
@@ -3478,14 +4626,17 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   auto multiply(Args... args) {
       return (args * ...);
   }
+
+
+The matcher cxxFoldExpr(isBinaryFold())
+matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>></td><td class="name" onclick="toggle('isLeftFold0')"><a name="isLeftFold0Anchor">isLeftFold</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isLeftFold0"><pre>Matches left-folding fold expressions.
 
-Example matches `(0 + ... + args)`
-    (matcher = cxxFoldExpr(isLeftFold()))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
@@ -3495,14 +4646,17 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   auto multiply(Args... args) {
       return (args * ... * 1);
   }
+
+
+The matcher cxxFoldExpr(isLeftFold())
+matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>></td><td class="name" onclick="toggle('isRightFold0')"><a name="isRightFold0Anchor">isRightFold</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isRightFold0"><pre>Matches right-folding fold expressions.
 
-Example matches `(args * ... * 1)`
-    (matcher = cxxFoldExpr(isRightFold()))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
@@ -3512,6 +4666,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   auto multiply(Args... args) {
       return (args * ... * 1);
   }
+
+
+The matcher cxxFoldExpr(isRightFold())
+matches (args * ... * 1).
 </pre></td></tr>
 
 
@@ -3519,8 +4677,7 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isUnaryFold0"><pre>Matches unary fold expressions, i.e. fold expressions without an
 initializer.
 
-Example matches `(args * ...)`
-    (matcher = cxxFoldExpr(isUnaryFold()))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
@@ -3530,6 +4687,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   auto multiply(Args... args) {
       return (args * ...);
   }
+
+
+The matcher cxxFoldExpr(isUnaryFold())
+matches (args * ...), but not (0 + ... + args).
 </pre></td></tr>
 
 
@@ -3542,7 +4703,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void bar();
 };
 
-cxxMethodDecl(isConst()) matches A::foo() but not A::bar()
+
+The matcher cxxMethodDecl(isConst())
+matches foo but not bar
 </pre></td></tr>
 
 
@@ -3556,8 +4719,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   A &operator=(A &&);
 };
 
-cxxMethodDecl(isCopyAssignmentOperator()) matches the first method but not
-the second one.
+
+The matcher cxxMethodDecl(isCopyAssignmentOperator())
+matches A &operator=(const A &)
+but does not match A &operator=(A &&)
 </pre></td></tr>
 
 
@@ -3573,15 +4738,19 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
  int operator+(int);
 };
 
-cxxMethodDecl(isExplicitObjectMemberFunction()) matches the first two
-methods but not the last two.
+
+The matcher cxxMethodDecl(isExplicitObjectMemberFunction())
+matches int operator-(this A, int) and
+void fun(this A &&self),
+but not static int operator()(int) or
+int operator+(int).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('isFinal1')"><a name="isFinal1Anchor">isFinal</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isFinal1"><pre>Matches if the given method or class declaration is final.
 
-Given:
+Given
   class A final {};
 
   struct B {
@@ -3591,7 +4760,13 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   struct C : B {
     void f() final;
   };
-matches A and C::f, but not B, C, or B::f
+
+The matcher cxxRecordDecl(isFinal())
+matches A,
+but does not match B or C.
+The matcher cxxMethodDecl(isFinal())
+matches void f() final in C ,
+but does not match virtual void f() in B .
 </pre></td></tr>
 
 
@@ -3605,8 +4780,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   A &operator=(A &&);
 };
 
-cxxMethodDecl(isMoveAssignmentOperator()) matches the second method but not
-the first one.
+
+The matcher cxxMethodDecl(isMoveAssignmentOperator())
+matches A &operator=(A &&)
+but does not match A &operator=(const A &)
 </pre></td></tr>
 
 
@@ -3620,9 +4797,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   };
   class B : public A {
    public:
-    virtual void x();
+    void x() override;
   };
-  matches B::x
+
+The matcher cxxMethodDecl(isOverride())
+  matches void x() override
 </pre></td></tr>
 
 
@@ -3634,7 +4813,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
    public:
     virtual void x() = 0;
   };
-  matches A::x
+
+The matcher cxxMethodDecl(isPure())
+matches virtual void x() = 0
 </pre></td></tr>
 
 
@@ -3647,7 +4828,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     S(const S &) = default; // #2
     S(S &&) = delete; // #3
   };
-cxxConstructorDecl(isUserProvided()) will match #1, but not #2 or #3.
+
+The matcher cxxConstructorDecl(isUserProvided())
+will match S(), but not S &) = default} or
+&&) = delete}
 </pre></td></tr>
 
 
@@ -3655,16 +4839,23 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isVirtual0"><pre>Matches declarations of virtual methods and C++ base specifers that specify
 virtual inheritance.
 
-Example:
+Given
   class A {
    public:
     virtual void x(); // matches x
   };
 
-Example:
-  class Base {};
-  class DirectlyDerived : virtual Base {}; // matches Base
-  class IndirectlyDerived : DirectlyDerived, Base {}; // matches Base
+The matcher cxxMethodDecl(isVirtual())
+matches x.
+
+Given
+  struct Base {};
+  struct DirectlyDerived : virtual Base {}; // matches Base
+  struct IndirectlyDerived : DirectlyDerived, Base {}; // matches Base
+
+The matcher
+cxxRecordDecl(hasDirectBase(cxxBaseSpecifier(isVirtual())))
+matches DirectlyDerived.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>
 </pre></td></tr>
@@ -3682,17 +4873,22 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
    public:
     void x();
   };
-  matches A::x but not B::x
+
+The matcher cxxMethodDecl(isVirtualAsWritten())
+matches virtual void x() of A,
+but does not match x()} of B .
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>></td><td class="name" onclick="toggle('isArray0')"><a name="isArray0Anchor">isArray</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isArray0"><pre>Matches array new expressions.
 
-Given:
+Given
+  struct MyClass { int x; };
   MyClass *p1 = new MyClass[10];
-cxxNewExpr(isArray())
-  matches the expression 'new MyClass[10]'.
+
+The matcher cxxNewExpr(isArray())
+matches new MyClass[10].
 </pre></td></tr>
 
 
@@ -3700,9 +4896,26 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasAnyOperatorName1"><pre>Matches operator expressions (binary or unary) that have any of the
 specified names.
 
+It provides a compact way of writing if an operator has any of the specified
+names:
+The matcher
    hasAnyOperatorName("+", "-")
- Is equivalent to
-   anyOf(hasOperatorName("+"), hasOperatorName("-"))
+Is equivalent to
+   hasOperatorName("-"))}
+
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+void bar(bool a, bool b) {
+  a && b;
+ }
+
+The matcher binaryOperator(hasAnyOperatorName("||", "&&"))
+matches a || b and a && b.
+The matcher unaryOperator(hasAnyOperatorName("-", "!"))
+matches !(a || b).
 </pre></td></tr>
 
 
@@ -3713,6 +4926,30 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 "operator" prefix: e.g. "<<".
 
   hasAnyOverloadedOperatorName("+", "-")
+
+Given
+  struct Point { double x; double y; };
+  Point operator+(const Point&, const Point&);
+  Point operator-(const Point&, const Point&);
+
+  Point sub(Point a, Point b) {
+    return b - a;
+  }
+
+
+The matcher functionDecl(hasAnyOverloadedOperatorName("+", "-")),
+which is equivalent to
+functionDecl(anyOf(hasAnyOverloadedOperatorName("+"),
+hasOverloadedOperatorName("-"))),
+matches Point operator+(const Point&, const Point&) and
+Point operator-(const Point&, const Point&).
+The matcher
+cxxOperatorCallExpr(hasAnyOverloadedOperatorName("+", "-")),
+which is equivalent to
+cxxOperatorCallExpr(anyOf(hasOverloadedOperatorName("+"),
+hasOverloadedOperatorName("-"))),
+matches b - a.
+
 Is equivalent to
   anyOf(hasOverloadedOperatorName("+"), hasOverloadedOperatorName("-"))
 </pre></td></tr>
@@ -3722,15 +4959,22 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperatorName1"><pre>Matches the operator Name of operator expressions and fold expressions
 (binary or unary).
 
-Example matches a || b (matcher = binaryOperator(hasOperatorName("||")))
-  !(a || b)
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+The matcher binaryOperator(hasOperatorName("||"))
+matches a || b
 
-Example matches `(0 + ... + args)`
-    (matcher = cxxFoldExpr(hasOperatorName("+")))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
   }
+
+The matcher cxxFoldExpr(hasOperatorName("+"))
+ matches (0 + ... + args).
 </pre></td></tr>
 
 
@@ -3740,16 +4984,19 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Matches overloaded operator names specified in strings without the
 "operator" prefix: e.g. "<<".
 
-Given:
-  class A { int operator*(); };
+Given
+  struct A { int operator*(); };
   const A &operator<<(const A &a, const A &b);
-  A a;
-  a << a;   // <-- This matches
+  void f(A a) {
+    a << a;   // <-- This matches
+  }
 
-cxxOperatorCallExpr(hasOverloadedOperatorName("<<"))) matches the
-specified line and
+
+The matcher cxxOperatorCallExpr(hasOverloadedOperatorName("<<"))
+matches a << a.
+The matcher
 cxxRecordDecl(hasMethod(hasOverloadedOperatorName("*")))
-matches the declaration of A.
+matches struct A { int operator*(); }.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>
 </pre></td></tr>
@@ -3758,47 +5005,104 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>></td><td class="name" onclick="toggle('isAssignmentOperator1')"><a name="isAssignmentOperator1Anchor">isAssignmentOperator</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isAssignmentOperator1"><pre>Matches all kinds of assignment operators.
 
-Example 1: matches a += b (matcher = binaryOperator(isAssignmentOperator()))
+Given
+void foo(int a, int b) {
   if (a == b)
     a += b;
+}
+The matcher binaryOperator(isAssignmentOperator())
+matches a += b.
 
-Example 2: matches s1 = s2
-           (matcher = cxxOperatorCallExpr(isAssignmentOperator()))
+Given
   struct S { S& operator=(const S&); };
   void x() { S s1, s2; s1 = s2; }
+
+The matcher cxxOperatorCallExpr(isAssignmentOperator())
+matches s1 = s2.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>></td><td class="name" onclick="toggle('isComparisonOperator1')"><a name="isComparisonOperator1Anchor">isComparisonOperator</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isComparisonOperator1"><pre>Matches comparison operators.
 
-Example 1: matches a == b (matcher = binaryOperator(isComparisonOperator()))
+Given
+void foo(int a, int b) {
   if (a == b)
     a += b;
+}
+The matcher binaryOperator(isComparisonOperator())
+matches a == b
 
-Example 2: matches s1 < s2
-           (matcher = cxxOperatorCallExpr(isComparisonOperator()))
+Given
   struct S { bool operator<(const S& other); };
   void x(S s1, S s2) { bool b1 = s1 < s2; }
+
+The matcher cxxOperatorCallExpr(isComparisonOperator())
+matches s1 < s2
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('hasDefinition0')"><a name="hasDefinition0Anchor">hasDefinition</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasDefinition0"><pre>Matches a class declaration that is defined.
 
-Example matches x (matcher = cxxRecordDecl(hasDefinition()))
+Given
 class x {};
 class y;
+
+The matcher cxxRecordDecl(hasDefinition())
+matches class x {}
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isDerivedFrom2')"><a name="isDerivedFrom2Anchor">isDerivedFrom</a></td><td>std::string BaseName</td></tr>
 <tr><td colspan="4" class="doc" id="isDerivedFrom2"><pre>Overloaded method as shortcut for isDerivedFrom(hasName(...)).
+
+Matches C++ classes that are directly or indirectly derived from a class
+matching Base, or Objective-C classes that directly or indirectly
+subclass a class matching Base.
+
+Note that a class is not considered to be derived from itself.
+
+Example matches Y, Z, C (Base == hasName("X"))
+  class X {};
+  class Y : public X {};  // directly derived
+  class Z : public Y {};  // indirectly derived
+  typedef X A;
+  typedef A B;
+  class C : public B {};  // derived from a typedef of X
+
+  class Foo {};
+  typedef Foo Alias;
+  class Bar : public Alias {};  // derived from Alias, which is a
+                                // typedef of Foo
+
+
+The matcher cxxRecordDecl(isDerivedFrom("X"))
+matches Y, Z and C.
+The matcher cxxRecordDecl(isDerivedFrom("Foo"))
+matches Bar.
+
+In the following example, Bar matches isDerivedFrom(hasName("NSObject"))
+  @interface NSObject @end
+  @interface Bar : NSObject @end
+
+
+Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCInterfaceDecl.html">ObjCInterfaceDecl</a>>
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isDirectlyDerivedFrom2')"><a name="isDirectlyDerivedFrom2Anchor">isDirectlyDerivedFrom</a></td><td>std::string BaseName</td></tr>
 <tr><td colspan="4" class="doc" id="isDirectlyDerivedFrom2"><pre>Overloaded method as shortcut for isDirectlyDerivedFrom(hasName(...)).
+
+Given
+  struct Base {};
+  struct DirectlyDerived : public Base {};
+  struct IndirectlyDerived : public DirectlyDerived {};
+
+
+The matcher cxxRecordDecl(isDirectlyDerivedFrom("Base"))
+matches DirectlyDerived, but not
+IndirectlyDerived.
 </pre></td></tr>
 
 
@@ -3809,8 +5113,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   template<typename T> void A(T t) { }
   template<> void A(int N) { }
-functionDecl(isExplicitTemplateSpecialization())
-  matches the specialization A<int>().
+
+The matcher functionDecl(isExplicitTemplateSpecialization())
+  matches the specialization template<> void A(int N) { }.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
 </pre></td></tr>
@@ -3819,7 +5124,7 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isFinal0')"><a name="isFinal0Anchor">isFinal</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isFinal0"><pre>Matches if the given method or class declaration is final.
 
-Given:
+Given
   class A final {};
 
   struct B {
@@ -3829,24 +5134,46 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   struct C : B {
     void f() final;
   };
-matches A and C::f, but not B, C, or B::f
+
+The matcher cxxRecordDecl(isFinal())
+matches A,
+but does not match B or C.
+The matcher cxxMethodDecl(isFinal())
+matches void f() final in C ,
+but does not match virtual void f() in B .
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isLambda0')"><a name="isLambda0Anchor">isLambda</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isLambda0"><pre>Matches the generated class of lambda expressions.
 
-Given:
+Given
   auto x = []{};
 
-cxxRecordDecl(isLambda()) matches the implicit class declaration of
-decltype(x)
+
+The matcher varDecl(hasType(cxxRecordDecl(isLambda())))
+matches auto x = []{}.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isSameOrDerivedFrom2')"><a name="isSameOrDerivedFrom2Anchor">isSameOrDerivedFrom</a></td><td>std::string BaseName</td></tr>
-<tr><td colspan="4" class="doc" id="isSameOrDerivedFrom2"><pre>Overloaded method as shortcut for
+<tr><td colspan="4" class="doc" id="isSameOrDerivedFrom2"><pre>Similar to isDerivedFrom(), but also matches classes that directly
+match Base.
+Overloaded method as shortcut for
 isSameOrDerivedFrom(hasName(...)).
+
+Given
+  class X {};
+  class Y : public X {};  // directly derived
+  class Z : public Y {};  // indirectly derived
+  typedef X A;
+  typedef A B;
+  class C : public B {};  // derived from a typedef of X
+
+The matcher
+cxxRecordDecl(isSameOrDerivedFrom("X"), isDefinition())
+matches class X {}, class Y : public X {},
+class Z : public Y {} and class C : public B {}.
 </pre></td></tr>
 
 
@@ -3855,18 +5182,36 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 member variable template instantiations.
 
 Given
-  template <typename T> class X {}; class A {}; X<A> x;
-or
-  template <typename T> class X {}; class A {}; template class X<A>;
-or
-  template <typename T> class X {}; class A {}; extern template class X<A>;
-cxxRecordDecl(hasName("::X"), isTemplateInstantiation())
-  matches the template instantiation of X<A>.
+  template <typename T> class X {};
+  class A {};
+  X<A> x;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches class X<class A>.
+  template <typename T> class X {};
+  class A {};
+  template class X<A>;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches template class X<A>
+  template <typename T> class X {};
+  class A {};
+  extern template class X<A>;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches extern template class X<A>
 
 But given
-  template <typename T>  class X {}; class A {};
-  template <> class X<A> {}; X<A> x;
-cxxRecordDecl(hasName("::X"), isTemplateInstantiation())
+  template <typename T>  class X {};
+  class A {};
+  template <> class X<A> {};
+  X<A> x;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
   does not match, as X<A> is an explicit template specialization.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
@@ -3877,9 +5222,26 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasAnyOperatorName2"><pre>Matches operator expressions (binary or unary) that have any of the
 specified names.
 
+It provides a compact way of writing if an operator has any of the specified
+names:
+The matcher
    hasAnyOperatorName("+", "-")
- Is equivalent to
-   anyOf(hasOperatorName("+"), hasOperatorName("-"))
+Is equivalent to
+   hasOperatorName("-"))}
+
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+void bar(bool a, bool b) {
+  a && b;
+ }
+
+The matcher binaryOperator(hasAnyOperatorName("||", "&&"))
+matches a || b and a && b.
+The matcher unaryOperator(hasAnyOperatorName("-", "!"))
+matches !(a || b).
 </pre></td></tr>
 
 
@@ -3887,43 +5249,62 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperatorName2"><pre>Matches the operator Name of operator expressions and fold expressions
 (binary or unary).
 
-Example matches a || b (matcher = binaryOperator(hasOperatorName("||")))
-  !(a || b)
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+The matcher binaryOperator(hasOperatorName("||"))
+matches a || b
 
-Example matches `(0 + ... + args)`
-    (matcher = cxxFoldExpr(hasOperatorName("+")))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
   }
+
+The matcher cxxFoldExpr(hasOperatorName("+"))
+ matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRewrittenBinaryOperator.html">CXXRewrittenBinaryOperator</a>></td><td class="name" onclick="toggle('isAssignmentOperator2')"><a name="isAssignmentOperator2Anchor">isAssignmentOperator</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isAssignmentOperator2"><pre>Matches all kinds of assignment operators.
 
-Example 1: matches a += b (matcher = binaryOperator(isAssignmentOperator()))
+Given
+void foo(int a, int b) {
   if (a == b)
     a += b;
+}
+The matcher binaryOperator(isAssignmentOperator())
+matches a += b.
 
-Example 2: matches s1 = s2
-           (matcher = cxxOperatorCallExpr(isAssignmentOperator()))
+Given
   struct S { S& operator=(const S&); };
   void x() { S s1, s2; s1 = s2; }
+
+The matcher cxxOperatorCallExpr(isAssignmentOperator())
+matches s1 = s2.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRewrittenBinaryOperator.html">CXXRewrittenBinaryOperator</a>></td><td class="name" onclick="toggle('isComparisonOperator2')"><a name="isComparisonOperator2Anchor">isComparisonOperator</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isComparisonOperator2"><pre>Matches comparison operators.
 
-Example 1: matches a == b (matcher = binaryOperator(isComparisonOperator()))
+Given
+void foo(int a, int b) {
   if (a == b)
     a += b;
+}
+The matcher binaryOperator(isComparisonOperator())
+matches a == b
 
-Example 2: matches s1 < s2
-           (matcher = cxxOperatorCallExpr(isComparisonOperator()))
+Given
   struct S { bool operator<(const S& other); };
   void x(S s1, S s2) { bool b1 = s1 < s2; }
+
+The matcher cxxOperatorCallExpr(isComparisonOperator())
+matches s1 < s2
 </pre></td></tr>
 
 
@@ -3931,12 +5312,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="argumentCountAtLeast2"><pre>Checks that a call expression or a constructor call expression has at least
 the specified number of arguments (including absent default arguments).
 
-Example matches f(0, 0) and g(0, 0, 0)
-(matcher = callExpr(argumentCountAtLeast(2)))
+Given
   void f(int x, int y);
   void g(int x, int y, int z);
-  f(0, 0);
-  g(0, 0, 0);
+  void foo() {
+    f(0, 0);
+    g(0, 0, 0);
+  }
+The matcher callExpr(argumentCountAtLeast(2))
+matches f(0, 0) and g(0, 0, 0)
 </pre></td></tr>
 
 
@@ -3944,9 +5328,13 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="argumentCountIs2"><pre>Checks that a call expression or a constructor call expression has
 a specific number of arguments (including absent default arguments).
 
-Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2)))
+Given
   void f(int x, int y);
-  f(0, 0);
+  void foo() {
+    f(0, 0);
+  }
+The matcher callExpr(argumentCountIs(2))
+matches f(0, 0)
 </pre></td></tr>
 
 
@@ -3954,12 +5342,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="argumentCountAtLeast0"><pre>Checks that a call expression or a constructor call expression has at least
 the specified number of arguments (including absent default arguments).
 
-Example matches f(0, 0) and g(0, 0, 0)
-(matcher = callExpr(argumentCountAtLeast(2)))
+Given
   void f(int x, int y);
   void g(int x, int y, int z);
-  f(0, 0);
-  g(0, 0, 0);
+  void foo() {
+    f(0, 0);
+    g(0, 0, 0);
+  }
+The matcher callExpr(argumentCountAtLeast(2))
+matches f(0, 0) and g(0, 0, 0)
 </pre></td></tr>
 
 
@@ -3967,16 +5358,20 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="argumentCountIs0"><pre>Checks that a call expression or a constructor call expression has
 a specific number of arguments (including absent default arguments).
 
-Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2)))
+Given
   void f(int x, int y);
-  f(0, 0);
+  void foo() {
+    f(0, 0);
+  }
+The matcher callExpr(argumentCountIs(2))
+matches f(0, 0)
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('usesADL0')"><a name="usesADL0Anchor">usesADL</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="usesADL0"><pre>Matches call expressions which were resolved using ADL.
 
-Example matches y(x) but not y(42) or NS::y(x).
+Given
   namespace NS {
     struct X {};
     void y(X);
@@ -3992,15 +5387,20 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     using NS::y;
     y(x); // Found by both unqualified lookup and ADL, doesn't match
    }
+
+
+The matcher callExpr(usesADL())
+matches y(x), but not y(42) or NS::y(x).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CastExpr.html">CastExpr</a>></td><td class="name" onclick="toggle('hasCastKind0')"><a name="hasCastKind0Anchor">hasCastKind</a></td><td>CastKind Kind</td></tr>
 <tr><td colspan="4" class="doc" id="hasCastKind0"><pre>Matches casts that has a given cast kind.
 
-Example: matches the implicit cast around 0
-(matcher = castExpr(hasCastKind(CK_NullToPointer)))
+Given
   int *p = 0;
+The matcher castExpr(hasCastKind(CK_NullToPointer))
+matches the implicit cast around 0
 
 If the matcher is use from clang-query, CastKind parameter
 should be passed as a quoted string. e.g., hasCastKind("CK_NullToPointer").
@@ -4015,22 +5415,27 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="equals3"><pre>Matches literals that are equal to the given value of type ValueT.
 
 Given
+void f(char, bool, double, int);
+void foo() {
   f('false, 3.14, 42);
-characterLiteral(equals(0))
-  matches 'cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
-  match false
-floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
-  match 3.14
-integerLiteral(equals(42))
-  matches 42
+}
+
+The matcher characterLiteral(equals(0U)) matches 'The matchers cxxBoolLiteral(equals(false)) and
+cxxBoolLiteral(equals(0)) match false.
+The matcher floatLiteral(equals(3.14)) matches 3.14.
+The matcher integerLiteral(equals(42)) matches 42.
 
 Note that you cannot directly match a negative numeric literal because the
 minus sign is not part of the literal: It is a unary operator whose operand
 is the positive numeric literal. Instead, you must use a unaryOperator()
 matcher to match the minus sign:
 
-unaryOperator(hasOperatorName("-"),
-              hasUnaryOperand(integerLiteral(equals(13))))
+Given
+  int val = -1;
+
+The matcher unaryOperator(hasOperatorName("-"),
+              hasUnaryOperand(integerLiteral(equals(1))))
+matches -1.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>>,
            Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>
@@ -4051,8 +5456,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   template<typename T> struct C {};
   C<int> c;
+
+The matcher
 classTemplateSpecializationDecl(templateArgumentCountIs(1))
-  matches C<int>.
+matches struct C<int>.
 </pre></td></tr>
 
 
@@ -4061,9 +5468,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 child statements.
 
 Example: Given
+void foo() {
   { for (;;) {} }
-compoundStmt(statementCountIs(0)))
-  matches '{}'
+}
+The matcher compoundStmt(statementCountIs(0))
+{}
   but does not match the outer compound statement.
 </pre></td></tr>
 
@@ -4078,10 +5487,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   char *s = "abcd";
   wchar_t *ws = L"abcd";
   char *w = "a";
-constantArrayType(hasSize(42))
-  matches "int a[42]" and "int b[2 * 21]"
-stringLiteral(hasSize(4))
-  matches "abcd", L"abcd"
+
+The matcher constantArrayType(hasSize(42))
+matches int[42] twice.
+The matcher stringLiteral(hasSize(4))
+matches "abcd" and L"abcd".
 </pre></td></tr>
 
 
@@ -4089,12 +5499,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="declCountIs0"><pre>Matches declaration statements that contain a specific number of
 declarations.
 
-Example: Given
-  int a, b;
-  int c;
-  int d = 2, e;
-declCountIs(2)
-  matches 'int a, b;' and 'int d = 2, e;', but not 'int c;'.
+Given
+  void foo() {
+    int a, b;
+    int c;
+    int d = 2, e;
+  }
+The matcher declStmt(declCountIs(2))
+matches int a, b; and int d = 2, e;,
+but does not match int c;
 </pre></td></tr>
 
 
@@ -4105,10 +5518,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
   class X { int a; int b; };
-cxxRecordDecl(
+
+The matcher cxxRecordDecl(
     has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
     has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
-  matches the class X, as a and b have the same type.
+  matches X, as a and b have the same type.
 
 Note that when multiple matches are involved via forEach* matchers,
 equalsBoundNodes acts as a filter.
@@ -4121,7 +5535,7 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 </pre></td></tr>
 
 
-<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsNode0')"><a name="equalsNode0Anchor">equalsNode</a></td><td>const Decl* Other</td></tr>
+<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsNode0')"><a name="equalsNode0Anchor">equalsNode</a></td><td>const Decl * Other</td></tr>
 <tr><td colspan="4" class="doc" id="equalsNode0"><pre>Matches if a node equals another node.
 
 Decl has pointer identity in the AST.
@@ -4132,10 +5546,13 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasAttr0"><pre>Matches declaration that has a given attribute.
 
 Given
-  __attribute__((device)) void f() { ... }
-decl(hasAttr(clang::attr::CUDADevice)) matches the function declaration of
-f. If the matcher is used from clang-query, attr::Kind parameter should be
-passed as a quoted string. e.g., hasAttr("attr::CUDADevice").
+  __attribute__((device)) void f() {}
+
+The matcher decl(hasAttr(clang::attr::CUDADevice))
+matches f.
+If the matcher is used from clang-query, attr::Kind
+parameter should be passed as a quoted string. e.g.,
+hasAttr("attr::CUDADevice").
 </pre></td></tr>
 
 
@@ -4144,6 +5561,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Does not match if only part of the statement is expanded from that macro or
 if different parts of the statement are expanded from different
 appearances of the macro.
+
+Given
+  #define A 0
+  #define B A
+  int c = B;
+
+The matcher integerLiteral(isExpandedFromMacro("A"))
+matches the literal expanded at the initializer B of the variable
+c .
 </pre></td></tr>
 
 
@@ -4151,12 +5577,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isExpansionInFileMatching0"><pre>Matches AST nodes that were expanded within files whose name is
 partially matching a given regex.
 
-Example matches Y but not X
-    (matcher = cxxRecordDecl(isExpansionInFileMatching("AST.*"))
-  #include "ASTMatcher.h"
-  class X {};
-ASTMatcher.h:
-  class Y {};
+Given the headers Y.h
+  #pragma once
+  typedef int my_y_int;
+and X.h
+  #pragma once
+  typedef int my_x_int;
+and the source code
+  #include "X.h"
+  #include "Y.h"
+  typedef int my_main_file_int;
+  my_main_file_int a = 0;
+  my_x_int b = 1;
+  my_y_int c = 2;
+
+The matcher
+typedefDecl(isExpansionInFileMatching("Y.h"))
+matches typedef int my_y_int,
+but does not match typedef int my_main_file_int or
+typedef int my_x_int.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 
@@ -4169,12 +5608,18 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isExpansionInMainFile0')"><a name="isExpansionInMainFile0Anchor">isExpansionInMainFile</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isExpansionInMainFile0"><pre>Matches AST nodes that were expanded within the main-file.
 
-Example matches X but not Y
-  (matcher = cxxRecordDecl(isExpansionInMainFile())
-  #include <Y.h>
-  class X {};
-Y.h:
-  class Y {};
+Given the header Y.h
+  #pragma once
+  typedef int my_header_int;
+and the source file
+  #include "Y.h"
+  typedef int my_main_file_int;
+  my_main_file_int a = 0;
+  my_header_int b = 1;
+
+The matcher typedefDecl(isExpansionInMainFile())
+matches typedef int my_main_file_int,
+but does not match typedef int my_header_int.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 </pre></td></tr>
@@ -4183,12 +5628,17 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isExpansionInSystemHeader0')"><a name="isExpansionInSystemHeader0Anchor">isExpansionInSystemHeader</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isExpansionInSystemHeader0"><pre>Matches AST nodes that were expanded within system-header-files.
 
-Example matches Y but not X
-    (matcher = cxxRecordDecl(isExpansionInSystemHeader())
+Given the header SystemHeader.h
+  #pragma once
+  int header();
+and the source code
   #include <SystemHeader.h>
-  class X {};
-SystemHeader.h:
-  class Y {};
+  static int main_file();
+
+
+The matcher functionDecl(isExpansionInSystemHeader())
+matches int header(),
+but does not match static int main_file().
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 </pre></td></tr>
@@ -4197,6 +5647,20 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isImplicit0')"><a name="isImplicit0Anchor">isImplicit</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isImplicit0"><pre>Matches an entity that has been implicitly added by the compiler (e.g.
 implicit default/copy constructors).
+
+Given
+  struct S {};
+  void f(S obj) {
+    S copy = obj;
+    [&](){ return copy; };
+  }
+
+
+The matcher cxxConstructorDecl(isImplicit(), isCopyConstructor())
+matches the implicit copy constructor of S.
+The matcher lambdaExpr(forEachLambdaCapture(
+    lambdaCapture(isImplicit()))) matches [&](){ return copy; },
+because it implicitly captures copy .
 </pre></td></tr>
 
 
@@ -4214,11 +5678,14 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   namespace {
     class vector {}; // #2
     namespace foo {
-      class vector{}; // #3
+      class vector {}; // #3
     }
   }
-cxxRecordDecl(hasName("vector"), isInAnonymousNamespace()) will match
-#1, #2 and #3.
+
+The matcher cxxRecordDecl(hasName("vector"),
+                        isInAnonymousNamespace())
+matches vector,
+twice per declaration at #1, #2 and #3.
 </pre></td></tr>
 
 
@@ -4241,7 +5708,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
       }
     }
   }
-cxxRecordDecl(hasName("vector"), isInStdNamespace()) will match only #1.
+
+The matcher cxxRecordDecl(hasName("vector"), isInStdNamespace())
+matches class vector {} inside of namespace std.
 </pre></td></tr>
 
 
@@ -4251,10 +5720,14 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
   template<typename T> void A(T t) { T i; }
-  A(0);
-  A(0U);
-functionDecl(isInstantiated())
-  matches 'A(int) {...};' and 'A(unsigned) {...}'.
+  void foo() {
+    A(0);
+    A(0U);
+  }
+
+The matcher functionDecl(isInstantiated())
+matches the two instantiations of void A(T t) { T i; } that
+are generated for int , and for int}.
 </pre></td></tr>
 
 
@@ -4262,16 +5735,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isPrivate0"><pre>Matches private C++ declarations and C++ base specifers that specify private
 inheritance.
 
-Examples:
+Given
   class C {
   public:    int a;
   protected: int b;
-  private:   int c; // fieldDecl(isPrivate()) matches 'c'
+  private:   int c;
   };
 
+The matcher fieldDecl(isPrivate())
+matches c.
+
   struct Base {};
-  struct Derived1 : private Base {}; // matches 'Base'
-  class Derived2 : Base {}; // matches 'Base'
+  struct Derived1 : private Base {}; // Base
+  class Derived2 : Base {}; // Base
+
+The matcher
+cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isPrivate()).bind("base")))
+matches Derived1 and Derived2, with
+cxxBaseSpecifier(isPrivate()) matching
+Base.
 </pre></td></tr>
 
 
@@ -4279,15 +5761,24 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isProtected0"><pre>Matches protected C++ declarations and C++ base specifers that specify
 protected inheritance.
 
-Examples:
+Given
   class C {
   public:    int a;
-  protected: int b; // fieldDecl(isProtected()) matches 'b'
+  protected: int b;
   private:   int c;
   };
 
+The matcher fieldDecl(isProtected())
+matches b.
+
   class Base {};
-  class Derived : protected Base {}; // matches 'Base'
+  class Derived : protected Base {};
+
+The matcher
+cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isProtected()).bind("base")))
+matches Derived, with
+cxxBaseSpecifier(isProtected()) matching
+Base.
 </pre></td></tr>
 
 
@@ -4295,16 +5786,26 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isPublic0"><pre>Matches public C++ declarations and C++ base specifers that specify public
 inheritance.
 
-Examples:
+Given
   class C {
-  public:    int a; // fieldDecl(isPublic()) matches 'a'
+  public:    int a;
   protected: int b;
   private:   int c;
   };
 
+The matcher fieldDecl(isPublic())
+matches a.
+
+Given
   class Base {};
-  class Derived1 : public Base {}; // matches 'Base'
-  struct Derived2 : Base {}; // matches 'Base'
+  class Derived1 : public Base {};
+  struct Derived2 : Base {};
+
+The matcher
+cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isPublic()).bind("base")))
+matches Derived1 and Derived2,
+with cxxBaseSpecifier(isPublic()) matching
+public Base and Base.
 </pre></td></tr>
 
 
@@ -4313,20 +5814,24 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 a specific number of designators.
 
 Example: Given
-  point ptarray[10] = { [2].y = 1.0, [0].x = 1.0 };
-  point ptarray2[10] = { [2].y = 1.0, [2].x = 0.0, [0].x = 1.0 };
-designatorCountIs(2)
-  matches '{ [2].y = 1.0, [0].x = 1.0 }',
-  but not '{ [2].y = 1.0, [2].x = 0.0, [0].x = 1.0 }'.
+  struct point2 { double x; double y; };
+  struct point2 ptarray[10] = { [0].x = 1.0 };
+  struct point2 pt = { .x = 2.0 };
+
+The matcher designatedInitExpr(designatorCountIs(2))
+matches [0].x = 1.0, but not .x = 2.0.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1EnumDecl.html">EnumDecl</a>></td><td class="name" onclick="toggle('isScoped0')"><a name="isScoped0Anchor">isScoped</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isScoped0"><pre>Matches C++11 scoped enum declaration.
 
-Example matches Y (matcher = enumDecl(isScoped()))
+Given
 enum X {};
 enum class Y {};
+
+The matcher enumDecl(isScoped())
+matches enum class Y {}
 </pre></td></tr>
 
 
@@ -4340,8 +5845,12 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 sizeof is known (std::size_t) and therefore the size of the outer
 sizeof is known.
   template<typename T>
-  void f(T x, T y) { sizeof(sizeof(T() + T()); }
-expr(isInstantiationDependent()) matches sizeof(sizeof(T() + T())
+  void f(T x, T y) { sizeof(T() + T()); }
+
+The matcher expr(isInstantiationDependent())
+matches sizeof(T() + T()),
+(T() + T()),
+T() + T() and T().
 </pre></td></tr>
 
 
@@ -4355,7 +5864,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void add(T x, int y) {
     x + y;
   }
-expr(isTypeDependent()) matches x + y
+
+The matcher expr(isTypeDependent())
+matches x + y and x.
 </pre></td></tr>
 
 
@@ -4366,7 +5877,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 For example, the array bound of "Chars" in the following example is
 value-dependent.
   template<int Size> int f() { return Size; }
-expr(isValueDependent()) matches return Size
+
+The matcher expr(isValueDependent())
+matches the return value Size.
 </pre></td></tr>
 
 
@@ -4374,16 +5887,22 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="nullPointerConstant0"><pre>Matches expressions that resolve to a null pointer constant, such as
 GNU's __null, C++11's nullptr, or C's NULL macro.
 
-Given:
+Given
+  #define NULL 0
   void *v1 = NULL;
   void *v2 = nullptr;
   void *v3 = __null; // GNU extension
   char *cp = (char *)0;
   int *ip = 0;
   int i = 0;
-expr(nullPointerConstant())
-  matches the initializer for v1, v2, v3, cp, and ip. Does not match the
-  initializer for i.
+
+The matcher expr(nullPointerConstant())
+matches the initializer NULL of v1,
+matches the initializer nullptr of v2,
+matches the initializer __null of v3,
+matches the initializer 0 of cp and
+matches the initializer 0 of ip,
+but does not match the initializer i of i.
 </pre></td></tr>
 
 
@@ -4397,8 +5916,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     int b : 4;
     int c : 2;
   };
-fieldDecl(hasBitWidth(2))
-  matches 'int a;' and 'int c;' but not 'int b;'.
+
+The matcher fieldDecl(hasBitWidth(2))
+matches a and c,
+but not b.
 </pre></td></tr>
 
 
@@ -4410,8 +5931,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     int a : 2;
     int b;
   };
-fieldDecl(isBitField())
-  matches 'int a;' but not 'int b;'.
+
+The matcher fieldDecl(isBitField())
+matches a,
+but does not match b.
 </pre></td></tr>
 
 
@@ -4419,22 +5942,27 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="equals1"><pre>Matches literals that are equal to the given value of type ValueT.
 
 Given
+void f(char, bool, double, int);
+void foo() {
   f('false, 3.14, 42);
-characterLiteral(equals(0))
-  matches 'cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
-  match false
-floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
-  match 3.14
-integerLiteral(equals(42))
-  matches 42
+}
+
+The matcher characterLiteral(equals(0U)) matches 'The matchers cxxBoolLiteral(equals(false)) and
+cxxBoolLiteral(equals(0)) match false.
+The matcher floatLiteral(equals(3.14)) matches 3.14.
+The matcher integerLiteral(equals(42)) matches 42.
 
 Note that you cannot directly match a negative numeric literal because the
 minus sign is not part of the literal: It is a unary operator whose operand
 is the positive numeric literal. Instead, you must use a unaryOperator()
 matcher to match the minus sign:
 
-unaryOperator(hasOperatorName("-"),
-              hasUnaryOperand(integerLiteral(equals(13))))
+Given
+  int val = -1;
+
+The matcher unaryOperator(hasOperatorName("-"),
+              hasUnaryOperand(integerLiteral(equals(1))))
+matches -1.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>>,
            Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>
@@ -4452,6 +5980,30 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 "operator" prefix: e.g. "<<".
 
   hasAnyOverloadedOperatorName("+", "-")
+
+Given
+  struct Point { double x; double y; };
+  Point operator+(const Point&, const Point&);
+  Point operator-(const Point&, const Point&);
+
+  Point sub(Point a, Point b) {
+    return b - a;
+  }
+
+
+The matcher functionDecl(hasAnyOverloadedOperatorName("+", "-")),
+which is equivalent to
+functionDecl(anyOf(hasAnyOverloadedOperatorName("+"),
+hasOverloadedOperatorName("-"))),
+matches Point operator+(const Point&, const Point&) and
+Point operator-(const Point&, const Point&).
+The matcher
+cxxOperatorCallExpr(hasAnyOverloadedOperatorName("+", "-")),
+which is equivalent to
+cxxOperatorCallExpr(anyOf(hasOverloadedOperatorName("+"),
+hasOverloadedOperatorName("-"))),
+matches b - a.
+
 Is equivalent to
   anyOf(hasOverloadedOperatorName("+"), hasOverloadedOperatorName("-"))
 </pre></td></tr>
@@ -4460,17 +6012,32 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasDynamicExceptionSpec0')"><a name="hasDynamicExceptionSpec0Anchor">hasDynamicExceptionSpec</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasDynamicExceptionSpec0"><pre>Matches functions that have a dynamic exception specification.
 
-Given:
-  void f();
-  void g() noexcept;
-  void h() noexcept(true);
-  void i() noexcept(false);
-  void j() throw();
-  void k() throw(int);
-  void l() throw(...);
-functionDecl(hasDynamicExceptionSpec()) and
-  functionProtoType(hasDynamicExceptionSpec())
-  match the declarations of j, k, and l, but not f, g, h, or i.
+Given
+  void f(int);
+  void g(int) noexcept;
+  void h(int) noexcept(true);
+  void i(int) noexcept(false);
+  void j(int) throw();
+  void k(int) throw(int);
+  void l(int) throw(...);
+
+The matcher functionDecl(hasDynamicExceptionSpec())
+matches the declarations void j(int) throw(),
+void k(int) throw(int)
+and void l(int) throw(...),
+but does not match void f(int), void g(int) noexcept,
+void h(int) noexcept(true)
+or void i(int) noexcept(true).
+The matcher
+functionProtoType(hasDynamicExceptionSpec()) matches
+the type void (int) throw() of j ,
+the type void (int) throw(int) of k and
+the type void (int) throw(...) of l .
+It does not match
+the type void (int) noexcept of f ,
+the type void (int) noexcept of g ,
+the type void (int) noexcept(int) of h or
+the type void (int) noexcept(...) of i .
 </pre></td></tr>
 
 
@@ -4480,16 +6047,19 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Matches overloaded operator names specified in strings without the
 "operator" prefix: e.g. "<<".
 
-Given:
-  class A { int operator*(); };
+Given
+  struct A { int operator*(); };
   const A &operator<<(const A &a, const A &b);
-  A a;
-  a << a;   // <-- This matches
+  void f(A a) {
+    a << a;   // <-- This matches
+  }
+
 
-cxxOperatorCallExpr(hasOverloadedOperatorName("<<"))) matches the
-specified line and
+The matcher cxxOperatorCallExpr(hasOverloadedOperatorName("<<"))
+matches a << a.
+The matcher
 cxxRecordDecl(hasMethod(hasOverloadedOperatorName("*")))
-matches the declaration of A.
+matches struct A { int operator*(); }.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>
 </pre></td></tr>
@@ -4498,9 +6068,12 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasTrailingReturn0')"><a name="hasTrailingReturn0Anchor">hasTrailingReturn</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasTrailingReturn0"><pre>Matches a function declared with a trailing return type.
 
-Example matches Y (matcher = functionDecl(hasTrailingReturn()))
+Given
 int X() {}
 auto Y() -> int {}
+
+The matcher functionDecl(hasTrailingReturn())
+matches auto Y() -> int {}.
 </pre></td></tr>
 
 
@@ -4508,15 +6081,18 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isConsteval0"><pre>Matches consteval function declarations and if consteval/if ! consteval
 statements.
 
-Given:
+Given
   consteval int a();
   void b() { if consteval {} }
   void c() { if ! consteval {} }
   void d() { if ! consteval {} else {} }
-functionDecl(isConsteval())
-  matches the declaration of "int a()".
-ifStmt(isConsteval())
-  matches the if statement in "void b()", "void c()", "void d()".
+
+The matcher functionDecl(isConsteval())
+matches a.
+The matcher ifStmt(isConsteval())
+matches the if statements
+if consteval {}, if ! consteval {} and
+if ! consteval {} else {}.
 </pre></td></tr>
 
 
@@ -4524,27 +6100,30 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isConstexpr1"><pre>Matches constexpr variable and function declarations,
        and if constexpr.
 
-Given:
+Given
   constexpr int foo = 42;
   constexpr int bar();
   void baz() { if constexpr(1 > 0) {} }
-varDecl(isConstexpr())
-  matches the declaration of foo.
-functionDecl(isConstexpr())
-  matches the declaration of bar.
-ifStmt(isConstexpr())
-  matches the if statement in baz.
+
+The matcher varDecl(isConstexpr())
+matches foo.
+The matcher functionDecl(isConstexpr())
+matches bar.
+The matcher ifStmt(isConstexpr())
+matches if constexpr(1 > 0) {}.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isDefaulted0')"><a name="isDefaulted0Anchor">isDefaulted</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isDefaulted0"><pre>Matches defaulted function declarations.
 
-Given:
+Given
   class A { ~A(); };
   class B { ~B() = default; };
-functionDecl(isDefaulted())
-  matches the declaration of ~B, but not ~A.
+
+The matcher functionDecl(isDefaulted())
+  matches ~B() = default,
+but does not match ~A().
 </pre></td></tr>
 
 
@@ -4558,6 +6137,14 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   extern int vb;  // Doesn't match, as it doesn't define the variable.
   void fa() {}
   void fb();  // Doesn't match, as it has no body.
+
+The matcher tagDecl(isDefinition())
+matches A
+The matcher varDecl(isDefinition())
+matches va
+The matcher functionDecl(isDefinition())
+matches fa
+
   @interface X
   - (void)ma; // Doesn't match, interface is declaration.
   @end
@@ -4565,6 +6152,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   - (void)ma {}
   @end
 
+The matcher objcMethodDecl(isDefinition())
+matches - (void)ma {}
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>>
 </pre></td></tr>
@@ -4573,11 +6163,13 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isDeleted0')"><a name="isDeleted0Anchor">isDeleted</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isDeleted0"><pre>Matches deleted function declarations.
 
-Given:
+Given
   void Func();
   void DeletedFunc() = delete;
-functionDecl(isDeleted())
-  matches the declaration of DeletedFunc, but not Func.
+
+The matcher functionDecl(isDeleted())
+matches DeletedFunc,
+but does not match Func.
 </pre></td></tr>
 
 
@@ -4588,8 +6180,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   template<typename T> void A(T t) { }
   template<> void A(int N) { }
-functionDecl(isExplicitTemplateSpecialization())
-  matches the specialization A<int>().
+
+The matcher functionDecl(isExplicitTemplateSpecialization())
+  matches the specialization template<> void A(int N) { }.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
 </pre></td></tr>
@@ -4598,17 +6191,21 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isExternC0')"><a name="isExternC0Anchor">isExternC</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isExternC0"><pre>Matches extern "C" function or variable declarations.
 
-Given:
+Given
   extern "C" void f() {}
   extern "C" { void g() {} }
   void h() {}
   extern "C" int x = 1;
   extern "C" int y = 2;
   int z = 3;
-functionDecl(isExternC())
-  matches the declaration of f and g, but not the declaration of h.
-varDecl(isExternC())
-  matches the declaration of x and y, but not the declaration of z.
+
+The matcher functionDecl(isExternC())
+matches f
+and g.
+The matcher varDecl(isExternC())
+matches x
+and y,
+but does not match z.
 </pre></td></tr>
 
 
@@ -4623,15 +6220,22 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   inline namespace m {}
   }
   inline int Foo = 5;
-functionDecl(isInline()) will match ::f().
-namespaceDecl(isInline()) will match n::m.
-varDecl(isInline()) will match Foo;
+
+The matcher functionDecl(isInline()) matches f.
+The matcher namespaceDecl(isInline()) matches m.
+The matcher varDecl(isInline()) matches Foo
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isMain0')"><a name="isMain0Anchor">isMain</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isMain0"><pre>Determines whether the function is "main", which is the entry point
 into an executable program.
+
+Given
+  void f();
+  int main() {}
+
+The matcher functionDecl(isMain()) matches int main() {}.
 </pre></td></tr>
 
 
@@ -4643,23 +6247,38 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   [[noreturn]] void a();
   __attribute__((noreturn)) void b();
   struct c { [[noreturn]] c(); };
-functionDecl(isNoReturn())
-  matches all of those except
-  void nope();
+
+The matcher functionDecl(isNoReturn())
+match a, b
+and c
+but do not match nope
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isNoThrow0')"><a name="isNoThrow0Anchor">isNoThrow</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isNoThrow0"><pre>Matches functions that have a non-throwing exception specification.
 
-Given:
-  void f();
-  void g() noexcept;
-  void h() throw();
-  void i() throw(int);
-  void j() noexcept(false);
-functionDecl(isNoThrow()) and functionProtoType(isNoThrow())
-  match the declarations of g, and h, but not f, i or j.
+Given
+  void f(int);
+  void g(int) noexcept;
+  void h(int) noexcept(false);
+  void i(int) throw();
+  void j(int) throw(int);
+
+The matcher functionDecl(isNoThrow())
+matches the declaration void g(int) noexcept
+and void i(int) throw(),
+but does not match void f(int),
+void h(int) noexcept(false)
+or void j(int) throw(int).
+The matcher
+functionProtoType(isNoThrow())
+matches the type void (int) throw() of i
+and the type void (int) noexcept of g,
+but does not match
+the type void (int) of f ,
+the type void (int) noexcept(false) of h or
+the type void (int) throw(int) of j .
 </pre></td></tr>
 
 
@@ -4667,15 +6286,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isStaticStorageClass0"><pre>Matches variable/function declarations that have "static" storage
 class specifier ("static" keyword) written in the source.
 
-Given:
+Given
   static void f() {}
   static int i = 0;
   extern int j;
   int k;
-functionDecl(isStaticStorageClass())
-  matches the function declaration f.
-varDecl(isStaticStorageClass())
-  matches the variable declaration i.
+The matcher functionDecl(isStaticStorageClass())
+  matches f
+The matcher varDecl(isStaticStorageClass())
+  matches i
 </pre></td></tr>
 
 
@@ -4684,18 +6303,36 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 member variable template instantiations.
 
 Given
-  template <typename T> class X {}; class A {}; X<A> x;
-or
-  template <typename T> class X {}; class A {}; template class X<A>;
-or
-  template <typename T> class X {}; class A {}; extern template class X<A>;
-cxxRecordDecl(hasName("::X"), isTemplateInstantiation())
-  matches the template instantiation of X<A>.
+  template <typename T> class X {};
+  class A {};
+  X<A> x;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches class X<class A>.
+  template <typename T> class X {};
+  class A {};
+  template class X<A>;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches template class X<A>
+  template <typename T> class X {};
+  class A {};
+  extern template class X<A>;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches extern template class X<A>
 
 But given
-  template <typename T>  class X {}; class A {};
-  template <> class X<A> {}; X<A> x;
-cxxRecordDecl(hasName("::X"), isTemplateInstantiation())
+  template <typename T>  class X {};
+  class A {};
+  template <> class X<A> {};
+  X<A> x;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
   does not match, as X<A> is an explicit template specialization.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
@@ -4711,17 +6348,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void g(int);
   template <typename... Ts> void h(Ts...);
   void i();
+
+The matcher functionDecl(isVariadic())
+matches void f(...),
+but does not match void g(int),
+template <typename... Ts> void h(Ts...),
+or void i().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isWeak0')"><a name="isWeak0Anchor">isWeak</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isWeak0"><pre>Matches weak function declarations.
 
-Given:
-  void foo() __attribute__((__weakref__("__foo")));
-  void bar();
-functionDecl(isWeak())
-  matches the weak declaration "foo", but not "bar".
+Given
+  static void f();
+  void g() __attribute__((weak));
+The matcher functionDecl(isWeak())
+  matches the weak declaration
+void g() __attribute__((weak)),
+but does not match static void foo_v1().
 </pre></td></tr>
 
 
@@ -4735,43 +6380,71 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void h(int i, int j);
   void j(int i);
   void k(int x, int y, int z, ...);
-functionDecl(parameterCountIs(2))
-  matches g and h
-functionProtoType(parameterCountIs(2))
-  matches g and h
-functionProtoType(parameterCountIs(3))
-  matches k
+The matcher functionDecl(parameterCountIs(2))
+matches g and h
+The matcher functionProtoType(parameterCountIs(1))
+matches the type void (int) of f and j.
+The matcher functionProtoType(parameterCountIs(3)) matches the
+type void (int, int, int, ...) of k.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionProtoType.html">FunctionProtoType</a>></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();
-  void g() noexcept;
-  void h() noexcept(true);
-  void i() noexcept(false);
-  void j() throw();
-  void k() throw(int);
-  void l() throw(...);
-functionDecl(hasDynamicExceptionSpec()) and
-  functionProtoType(hasDynamicExceptionSpec())
-  match the declarations of j, k, and l, but not f, g, h, or i.
+Given
+  void f(int);
+  void g(int) noexcept;
+  void h(int) noexcept(true);
+  void i(int) noexcept(false);
+  void j(int) throw();
+  void k(int) throw(int);
+  void l(int) throw(...);
+
+The matcher functionDecl(hasDynamicExceptionSpec())
+matches the declarations void j(int) throw(),
+void k(int) throw(int)
+and void l(int) throw(...),
+but does not match void f(int), void g(int) noexcept,
+void h(int) noexcept(true)
+or void i(int) noexcept(true).
+The matcher
+functionProtoType(hasDynamicExceptionSpec()) matches
+the type void (int) throw() of j ,
+the type void (int) throw(int) of k and
+the type void (int) throw(...) of l .
+It does not match
+the type void (int) noexcept of f ,
+the type void (int) noexcept of g ,
+the type void (int) noexcept(int) of h or
+the type void (int) noexcept(...) of i .
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionProtoType.html">FunctionProtoType</a>></td><td class="name" onclick="toggle('isNoThrow1')"><a name="isNoThrow1Anchor">isNoThrow</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isNoThrow1"><pre>Matches functions that have a non-throwing exception specification.
 
-Given:
-  void f();
-  void g() noexcept;
-  void h() throw();
-  void i() throw(int);
-  void j() noexcept(false);
-functionDecl(isNoThrow()) and functionProtoType(isNoThrow())
-  match the declarations of g, and h, but not f, i or j.
+Given
+  void f(int);
+  void g(int) noexcept;
+  void h(int) noexcept(false);
+  void i(int) throw();
+  void j(int) throw(int);
+
+The matcher functionDecl(isNoThrow())
+matches the declaration void g(int) noexcept
+and void i(int) throw(),
+but does not match void f(int),
+void h(int) noexcept(false)
+or void j(int) throw(int).
+The matcher
+functionProtoType(isNoThrow())
+matches the type void (int) throw() of i
+and the type void (int) noexcept of g,
+but does not match
+the type void (int) of f ,
+the type void (int) noexcept(false) of h or
+the type void (int) throw(int) of j .
 </pre></td></tr>
 
 
@@ -4785,12 +6458,12 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void h(int i, int j);
   void j(int i);
   void k(int x, int y, int z, ...);
-functionDecl(parameterCountIs(2))
-  matches g and h
-functionProtoType(parameterCountIs(2))
-  matches g and h
-functionProtoType(parameterCountIs(3))
-  matches k
+The matcher functionDecl(parameterCountIs(2))
+matches g and h
+The matcher functionProtoType(parameterCountIs(1))
+matches the type void (int) of f and j.
+The matcher functionProtoType(parameterCountIs(3)) matches the
+type void (int, int, int, ...) of k.
 </pre></td></tr>
 
 
@@ -4798,15 +6471,18 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isConsteval1"><pre>Matches consteval function declarations and if consteval/if ! consteval
 statements.
 
-Given:
+Given
   consteval int a();
   void b() { if consteval {} }
   void c() { if ! consteval {} }
   void d() { if ! consteval {} else {} }
-functionDecl(isConsteval())
-  matches the declaration of "int a()".
-ifStmt(isConsteval())
-  matches the if statement in "void b()", "void c()", "void d()".
+
+The matcher functionDecl(isConsteval())
+matches a.
+The matcher ifStmt(isConsteval())
+matches the if statements
+if consteval {}, if ! consteval {} and
+if ! consteval {} else {}.
 </pre></td></tr>
 
 
@@ -4814,16 +6490,17 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isConstexpr2"><pre>Matches constexpr variable and function declarations,
        and if constexpr.
 
-Given:
+Given
   constexpr int foo = 42;
   constexpr int bar();
   void baz() { if constexpr(1 > 0) {} }
-varDecl(isConstexpr())
-  matches the declaration of foo.
-functionDecl(isConstexpr())
-  matches the declaration of bar.
-ifStmt(isConstexpr())
-  matches the if statement in baz.
+
+The matcher varDecl(isConstexpr())
+matches foo.
+The matcher functionDecl(isConstexpr())
+matches bar.
+The matcher ifStmt(isConstexpr())
+matches if constexpr(1 > 0) {}.
 </pre></td></tr>
 
 
@@ -4835,22 +6512,27 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="equals0"><pre>Matches literals that are equal to the given value of type ValueT.
 
 Given
+void f(char, bool, double, int);
+void foo() {
   f('false, 3.14, 42);
-characterLiteral(equals(0))
-  matches 'cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
-  match false
-floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
-  match 3.14
-integerLiteral(equals(42))
-  matches 42
+}
+
+The matcher characterLiteral(equals(0U)) matches 'The matchers cxxBoolLiteral(equals(false)) and
+cxxBoolLiteral(equals(0)) match false.
+The matcher floatLiteral(equals(3.14)) matches 3.14.
+The matcher integerLiteral(equals(42)) matches 42.
 
 Note that you cannot directly match a negative numeric literal because the
 minus sign is not part of the literal: It is a unary operator whose operand
 is the positive numeric literal. Instead, you must use a unaryOperator()
 matcher to match the minus sign:
 
-unaryOperator(hasOperatorName("-"),
-              hasUnaryOperand(integerLiteral(equals(13))))
+Given
+  int val = -1;
+
+The matcher unaryOperator(hasOperatorName("-"),
+              hasUnaryOperand(integerLiteral(equals(1))))
+matches -1.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>>,
            Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>>
@@ -4876,14 +6558,30 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
     return l();
   }
 };
+
+The matcher
 lambdaExpr(hasAnyCapture(lambdaCapture(capturesThis())))
-  matches `[this]() { return cc; }`.
+matches [this]() { return cc; }.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaCapture.html">LambdaCapture</a>></td><td class="name" onclick="toggle('isImplicit2')"><a name="isImplicit2Anchor">isImplicit</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isImplicit2"><pre>Matches an entity that has been implicitly added by the compiler (e.g.
 implicit default/copy constructors).
+
+Given
+  struct S {};
+  void f(S obj) {
+    S copy = obj;
+    [&](){ return copy; };
+  }
+
+
+The matcher cxxConstructorDecl(isImplicit(), isCopyConstructor())
+matches the implicit copy constructor of S.
+The matcher lambdaExpr(forEachLambdaCapture(
+    lambdaCapture(isImplicit()))) matches [&](){ return copy; },
+because it implicitly captures copy .
 </pre></td></tr>
 
 
@@ -4902,14 +6600,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   };
   template <class T>
   class Z {
-    void x() { this->m; }
+    void x() {
+      this->m;
+      this->t;
+      this->t->m;
+    }
+    int m;
+    T* t;
   };
-memberExpr(isArrow())
-  matches this->x, x, y.x, a, this->b
-cxxDependentScopeMemberExpr(isArrow())
-  matches this->m
-unresolvedMemberExpr(isArrow())
-  matches this->f<T>, f<T>
+
+The matcher memberExpr(isArrow())
+matches this->x, x, a,
+this->b, this->m and two times this->t,
+once for the standalone member expression, and once for the member
+expression that later accesses m .
+Additionally, it does not match this->t->t.
+The matcher cxxDependentScopeMemberExpr(isArrow())
+matches this->t->m, but not this->m or this->t.
+The matcher unresolvedMemberExpr(isArrow())
+matches this->f<T>, f<T>
 </pre></td></tr>
 
 
@@ -4917,29 +6626,43 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasAnyName0"><pre>Matches NamedDecl nodes that have any of the specified names.
 
 This matcher is only provided as a performance optimization of hasName.
-    hasAnyName(a, b, c)
- is equivalent to, but faster than
-    anyOf(hasName(a), hasName(b), hasName(c))
+
+Given
+  void f(int a, int b);
+
+The matcher namedDecl(hasAnyName("a", "b")),
+which is equivalent to the matcher
+namedDecl(hasAnyName("a", "b")),
+matches int a and int b, but not
+void f(int a, int b).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>></td><td class="name" onclick="toggle('hasExternalFormalLinkage0')"><a name="hasExternalFormalLinkage0Anchor">hasExternalFormalLinkage</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasExternalFormalLinkage0"><pre>Matches a declaration that has external formal linkage.
 
-Example matches only z (matcher = varDecl(hasExternalFormalLinkage()))
+Given
 void f() {
-  int x;
-  static int y;
+  int a;
+  static int b;
 }
-int z;
+int c;
+static int d;
+The matcher varDecl(hasExternalFormalLinkage())
+matches int c,
+but not int a, static int b or int d.
 
-Example matches f() because it has external formal linkage despite being
-unique to the translation unit as though it has internal likage
-(matcher = functionDecl(hasExternalFormalLinkage()))
+Given
+  namespace {
+    void f() {}
+  }
+  void g() {}
+  static void h() {}
 
-namespace {
-void f() {}
-}
+
+The matcher functionDecl(hasExternalFormalLinkage())
+matches void g() {}, but not void f() {} or
+static void h() {}.
 </pre></td></tr>
 
 
@@ -4950,11 +6673,22 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 with '<enclosing>::'.
 Does not match typedefs of an underlying type with the given name.
 
-Example matches X (Name == "X")
+Given
   class X;
 
-Example matches X (Name is one of "::a::b::X", "a::b::X", "b::X", "X")
+
+The matcher namedDecl(hasName("X"))
+matches class X.
+
+Given
   namespace a { namespace b { class X; } }
+
+
+The matchers namedDecl(hasName("::a::b::X")),
+namedDecl(hasName("a::b::X")),
+namedDecl(hasName("b::X")) and
+namedDecl(hasName("X"))
+match class X.
 </pre></td></tr>
 
 
@@ -4966,12 +6700,13 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 prefixing the name with '<enclosing>::'.  Does not match typedefs
 of an underlying type with the given name.
 
-Example matches X (regexp == "::X")
-  class X;
-
-Example matches X (regexp is one of "::X", "^foo::.*X", among others)
+Given
   namespace foo { namespace bar { class X; } }
 
+
+The matcher namedDecl(matchesName("^::foo:.*X"))
+matches class X.
+
 If the matcher is used in clang-query, RegexFlags parameter
 should be passed as a quoted string. e.g: "NoFlags".
 Flags can be combined with '|' example "IgnoreCase | BasicRegex"
@@ -4985,7 +6720,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   namespace n {
   namespace {} // #1
   }
-namespaceDecl(isAnonymous()) will match #1 but not ::n.
+
+The matcher namespaceDecl(isAnonymous())
+matches namespace {}, but not namespace n.
 </pre></td></tr>
 
 
@@ -5000,9 +6737,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   inline namespace m {}
   }
   inline int Foo = 5;
-functionDecl(isInline()) will match ::f().
-namespaceDecl(isInline()) will match n::m.
-varDecl(isInline()) will match Foo;
+
+The matcher functionDecl(isInline()) matches f.
+The matcher namespaceDecl(isInline()) matches m.
+The matcher varDecl(isInline()) matches Foo
 </pre></td></tr>
 
 
@@ -5011,15 +6749,23 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 specified.
 
 Given
+  void foo() {
+    #pragma omp parallel
+      ;
+    #pragma omp parallel default(none)
+      ;
+    #pragma omp parallel default(shared)
+      ;
+    #pragma omp parallel default(private)
+      ;
+    #pragma omp parallel default(firstprivate)
+      ;
+  }
 
-  #pragma omp parallel
-  #pragma omp parallel default(none)
-  #pragma omp parallel default(shared)
-  #pragma omp parallel default(private)
-  #pragma omp parallel default(firstprivate)
 
-``ompDefaultClause(isFirstPrivateKind())`` matches only
-``default(firstprivate)``.
+The matcher
+ompExecutableDirective(hasAnyClause(ompDefaultClause(isFirstPrivateKind())))
+matches #pragma omp parallel default(firstprivate).
 </pre></td></tr>
 
 
@@ -5027,14 +6773,23 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isNoneKind0"><pre>Matches if the OpenMP ``default`` clause has ``none`` kind specified.
 
 Given
+  void foo() {
+    #pragma omp parallel
+      ;
+    #pragma omp parallel default(none)
+      ;
+    #pragma omp parallel default(shared)
+      ;
+    #pragma omp parallel default(private)
+      ;
+    #pragma omp parallel default(firstprivate)
+      ;
+  }
 
-  #pragma omp parallel
-  #pragma omp parallel default(none)
-  #pragma omp parallel default(shared)
-  #pragma omp parallel default(private)
-  #pragma omp parallel default(firstprivate)
 
-``ompDefaultClause(isNoneKind())`` matches only ``default(none)``.
+The matcher
+ompExecutableDirective(hasAnyClause(ompDefaultClause(isNoneKind())))
+matches only #pragma omp parallel default(none).
 </pre></td></tr>
 
 
@@ -5043,15 +6798,23 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 specified.
 
 Given
-
-  #pragma omp parallel
+  void foo() {
+    #pragma omp parallel
+      ;
   #pragma omp parallel default(none)
+      ;
   #pragma omp parallel default(shared)
+      ;
   #pragma omp parallel default(private)
+      ;
   #pragma omp parallel default(firstprivate)
+      ;
+  }
+
 
-``ompDefaultClause(isPrivateKind())`` matches only
-``default(private)``.
+The matcher
+ompExecutableDirective(hasAnyClause(ompDefaultClause(isPrivateKind())))
+matches #pragma omp parallel default(private).
 </pre></td></tr>
 
 
@@ -5059,14 +6822,23 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isSharedKind0"><pre>Matches if the OpenMP ``default`` clause has ``shared`` kind specified.
 
 Given
-
-  #pragma omp parallel
-  #pragma omp parallel default(none)
+  void foo() {
+    #pragma omp parallel
+      ;
+    #pragma omp parallel default(none)
+      ;
   #pragma omp parallel default(shared)
+      ;
   #pragma omp parallel default(private)
+      ;
   #pragma omp parallel default(firstprivate)
+      ;
+  }
 
-``ompDefaultClause(isSharedKind())`` matches only ``default(shared)``.
+
+The matcher
+ompExecutableDirective(hasAnyClause(ompDefaultClause(isSharedKind())))
+matches #pragma omp parallel default(shared).
 </pre></td></tr>
 
 
@@ -5075,13 +6847,21 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 clause kind.
 
 Given
+  void foo() {
+    #pragma omp parallel
+      ;
+    #pragma omp parallel for
+      for (int i = 0; i < 10; ++i) {}
+    #pragma omp          for
+      for (int i = 0; i < 10; ++i) {}
+  }
 
-  #pragma omp parallel
-  #pragma omp parallel for
-  #pragma omp          for
 
-`ompExecutableDirective(isAllowedToContainClause(OMPC_default))`` matches
-``omp parallel`` and ``omp parallel for``.
+The matcher
+ompExecutableDirective(isAllowedToContainClauseKind(
+OpenMPClauseKind::OMPC_default))
+matches #pragma omp parallel
+and #pragma omp parallel for.
 
 If the matcher is use from clang-query, ``OpenMPClauseKind`` parameter
 should be passed as a quoted string. e.g.,
@@ -5094,29 +6874,89 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 i.e., directives that can't have a structured block.
 
 Given
+  void foo() {
+    #pragma omp parallel
+    {
+      #pragma omp taskyield
+    }
+  }
 
-  #pragma omp parallel
-  {}
-  #pragma omp taskyield
 
-``ompExecutableDirective(isStandaloneDirective()))`` matches
-``omp taskyield``.
+The matcher ompExecutableDirective(isStandaloneDirective())
+matches #pragma omp taskyield.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCInterfaceDecl.html">ObjCInterfaceDecl</a>></td><td class="name" onclick="toggle('isDerivedFrom3')"><a name="isDerivedFrom3Anchor">isDerivedFrom</a></td><td>std::string BaseName</td></tr>
 <tr><td colspan="4" class="doc" id="isDerivedFrom3"><pre>Overloaded method as shortcut for isDerivedFrom(hasName(...)).
+
+Matches C++ classes that are directly or indirectly derived from a class
+matching Base, or Objective-C classes that directly or indirectly
+subclass a class matching Base.
+
+Note that a class is not considered to be derived from itself.
+
+Example matches Y, Z, C (Base == hasName("X"))
+  class X {};
+  class Y : public X {};  // directly derived
+  class Z : public Y {};  // indirectly derived
+  typedef X A;
+  typedef A B;
+  class C : public B {};  // derived from a typedef of X
+
+  class Foo {};
+  typedef Foo Alias;
+  class Bar : public Alias {};  // derived from Alias, which is a
+                                // typedef of Foo
+
+
+The matcher cxxRecordDecl(isDerivedFrom("X"))
+matches Y, Z and C.
+The matcher cxxRecordDecl(isDerivedFrom("Foo"))
+matches Bar.
+
+In the following example, Bar matches isDerivedFrom(hasName("NSObject"))
+  @interface NSObject @end
+  @interface Bar : NSObject @end
+
+
+Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCInterfaceDecl.html">ObjCInterfaceDecl</a>>
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCInterfaceDecl.html">ObjCInterfaceDecl</a>></td><td class="name" onclick="toggle('isDirectlyDerivedFrom3')"><a name="isDirectlyDerivedFrom3Anchor">isDirectlyDerivedFrom</a></td><td>std::string BaseName</td></tr>
 <tr><td colspan="4" class="doc" id="isDirectlyDerivedFrom3"><pre>Overloaded method as shortcut for isDirectlyDerivedFrom(hasName(...)).
+
+Given
+  struct Base {};
+  struct DirectlyDerived : public Base {};
+  struct IndirectlyDerived : public DirectlyDerived {};
+
+
+The matcher cxxRecordDecl(isDirectlyDerivedFrom("Base"))
+matches DirectlyDerived, but not
+IndirectlyDerived.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCInterfaceDecl.html">ObjCInterfaceDecl</a>></td><td class="name" onclick="toggle('isSameOrDerivedFrom3')"><a name="isSameOrDerivedFrom3Anchor">isSameOrDerivedFrom</a></td><td>std::string BaseName</td></tr>
-<tr><td colspan="4" class="doc" id="isSameOrDerivedFrom3"><pre>Overloaded method as shortcut for
+<tr><td colspan="4" class="doc" id="isSameOrDerivedFrom3"><pre>Similar to isDerivedFrom(), but also matches classes that directly
+match Base.
+Overloaded method as shortcut for
 isSameOrDerivedFrom(hasName(...)).
+
+Given
+  class X {};
+  class Y : public X {};  // directly derived
+  class Z : public Y {};  // indirectly derived
+  typedef X A;
+  typedef A B;
+  class C : public B {};  // derived from a typedef of X
+
+The matcher
+cxxRecordDecl(isSameOrDerivedFrom("X"), isDefinition())
+matches class X {}, class Y : public X {},
+class Z : public Y {} and class C : public B {}.
 </pre></td></tr>
 
 
@@ -5124,12 +6964,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="argumentCountAtLeast3"><pre>Checks that a call expression or a constructor call expression has at least
 the specified number of arguments (including absent default arguments).
 
-Example matches f(0, 0) and g(0, 0, 0)
-(matcher = callExpr(argumentCountAtLeast(2)))
+Given
   void f(int x, int y);
   void g(int x, int y, int z);
-  f(0, 0);
-  g(0, 0, 0);
+  void foo() {
+    f(0, 0);
+    g(0, 0, 0);
+  }
+The matcher callExpr(argumentCountAtLeast(2))
+matches f(0, 0) and g(0, 0, 0)
 </pre></td></tr>
 
 
@@ -5137,9 +6980,13 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="argumentCountIs3"><pre>Checks that a call expression or a constructor call expression has
 a specific number of arguments (including absent default arguments).
 
-Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2)))
+Given
   void f(int x, int y);
-  f(0, 0);
+  void foo() {
+    f(0, 0);
+  }
+The matcher callExpr(argumentCountIs(2))
+matches f(0, 0)
 </pre></td></tr>
 
 
@@ -5147,24 +6994,27 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasAnySelector0"><pre>Matches when at least one of the supplied string equals to the
 Selector.getAsString()
 
- matcher = objCMessageExpr(hasSelector("methodA:", "methodB:"));
- matches both of the expressions below:
     [myObj methodA:argA];
     [myObj methodB:argB];
+
+ The matcher objCMessageExpr(hasSelector("methodA:", "methodB:"));
+ matches [myObj methodA:argA]; and [myObj methodB:argB];
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('hasKeywordSelector0')"><a name="hasKeywordSelector0Anchor">hasKeywordSelector</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasKeywordSelector0"><pre>Matches when the selector is a keyword selector
 
-objCMessageExpr(hasKeywordSelector()) matches the generated setFrame
-message expression in
-
+Given
   UIWebView *webView = ...;
   CGRect bodyFrame = webView.frame;
   bodyFrame.size.height = self.bodyContentHeight;
   webView.frame = bodyFrame;
   //     ^---- matches here
+
+
+The matcher objCMessageExpr(hasKeywordSelector()) matches the
+generated setFrame message expression in
 </pre></td></tr>
 
 
@@ -5179,56 +7029,68 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('hasSelector0')"><a name="hasSelector0Anchor">hasSelector</a></td><td>std::string BaseName</td></tr>
 <tr><td colspan="4" class="doc" id="hasSelector0"><pre>Matches when BaseName == Selector.getAsString()
 
- matcher = objCMessageExpr(hasSelector("loadHTMLString:baseURL:"));
- matches the outer message expr in the code below, but NOT the message
- invocation for self.bodyView.
     [self.bodyView loadHTMLString:html baseURL:NULL];
+
+The matcher
+objCMessageExpr(hasSelector("loadHTMLString:baseURL:")); matches
+the outer message expr in the code below, but NOT the message invocation
+for self.bodyView.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('hasUnarySelector0')"><a name="hasUnarySelector0Anchor">hasUnarySelector</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasUnarySelector0"><pre>Matches when the selector is a Unary Selector
 
- matcher = objCMessageExpr(matchesSelector(hasUnarySelector());
- matches self.bodyView in the code below, but NOT the outer message
- invocation of "loadHTMLString:baseURL:".
+Given
     [self.bodyView loadHTMLString:html baseURL:NULL];
+
+
+ The matcher objCMessageExpr(matchesSelector(hasUnarySelector());
+ matches self.bodyView, but does not match the outer message
+ invocation of "loadHTMLString:baseURL:".
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('isClassMessage0')"><a name="isClassMessage0Anchor">isClassMessage</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isClassMessage0"><pre>Returns true when the Objective-C message is sent to a class.
 
-Example
-matcher = objcMessageExpr(isClassMessage())
-matches
+Given
   [NSString stringWithFormat:@"format"];
-but not
   NSString *x = @"hello";
   [x containsString:@"h"];
+
+The matcher objcMessageExpr(isClassMessage())
+matches [NSString stringWithFormat:@"format"];
+but does not match [[x containsString:@"h"]
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('isInstanceMessage0')"><a name="isInstanceMessage0Anchor">isInstanceMessage</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isInstanceMessage0"><pre>Returns true when the Objective-C message is sent to an instance.
 
-Example
-matcher = objcMessageExpr(isInstanceMessage())
-matches
+Given
   NSString *x = @"hello";
   [x containsString:@"h"];
-but not
   [NSString stringWithFormat:@"format"];
+
+The matcher objcMessageExpr(isInstanceMessage())
+matches [x containsString:@"h"];
+but does not match [NSString stringWithFormat:@"format"];
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('matchesSelector0')"><a name="matchesSelector0Anchor">matchesSelector</a></td><td>StringRef RegExp, Regex::RegexFlags Flags = NoFlags</td></tr>
 <tr><td colspan="4" class="doc" id="matchesSelector0"><pre>Matches ObjC selectors whose name contains
 a substring matched by the given RegExp.
- matcher = objCMessageExpr(matchesSelector("loadHTMLStringmatches the outer message expr in the code below, but NOT the message
- invocation for self.bodyView.
+
+Given
     [self.bodyView loadHTMLString:html baseURL:NULL];
 
+
+The matcher
+objCMessageExpr(matchesSelector("loadHTMLStringmatches the outer message expr in the code below, but NOT the message
+invocation for self.bodyView.
+
 If the matcher is used in clang-query, RegexFlags parameter
 should be passed as a quoted string. e.g: "NoFlags".
 Flags can be combined with '|' example "IgnoreCase | BasicRegex"
@@ -5238,25 +7100,26 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('numSelectorArgs0')"><a name="numSelectorArgs0Anchor">numSelectorArgs</a></td><td>unsigned N</td></tr>
 <tr><td colspan="4" class="doc" id="numSelectorArgs0"><pre>Matches when the selector has the specified number of arguments
 
- matcher = objCMessageExpr(numSelectorArgs(0));
- matches self.bodyView in the code below
-
- matcher = objCMessageExpr(numSelectorArgs(2));
- matches the invocation of "loadHTMLString:baseURL:" but not that
- of self.bodyView
     [self.bodyView loadHTMLString:html baseURL:NULL];
+
+The matcher objCMessageExpr(numSelectorArgs(0))
+matches self.bodyView.
+The matcher objCMessageExpr(numSelectorArgs(2))
+matches the invocation of loadHTMLString:baseURL:
+but does not match self.bodyView
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>></td><td class="name" onclick="toggle('isClassMethod0')"><a name="isClassMethod0Anchor">isClassMethod</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isClassMethod0"><pre>Returns true when the Objective-C method declaration is a class method.
 
-Example
-matcher = objcMethodDecl(isClassMethod())
-matches
+Given
 @interface I + (void)foo; @end
-but not
 @interface I - (void)bar; @end
+
+The matcher objcMethodDecl(isClassMethod())
+matches @interface I + (void)foo; @end
+but does not match interface I + (void)foo; @end
 </pre></td></tr>
 
 
@@ -5270,6 +7133,14 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   extern int vb;  // Doesn't match, as it doesn't define the variable.
   void fa() {}
   void fb();  // Doesn't match, as it has no body.
+
+The matcher tagDecl(isDefinition())
+matches A
+The matcher varDecl(isDefinition())
+matches va
+The matcher functionDecl(isDefinition())
+matches fa
+
   @interface X
   - (void)ma; // Doesn't match, interface is declaration.
   @end
@@ -5277,6 +7148,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   - (void)ma {}
   @end
 
+The matcher objcMethodDecl(isDefinition())
+matches - (void)ma {}
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>>
 </pre></td></tr>
@@ -5285,33 +7159,39 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>></td><td class="name" onclick="toggle('isInstanceMethod0')"><a name="isInstanceMethod0Anchor">isInstanceMethod</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isInstanceMethod0"><pre>Returns true when the Objective-C method declaration is an instance method.
 
-Example
-matcher = objcMethodDecl(isInstanceMethod())
-matches
+Given
 @interface I - (void)bar; @end
-but not
 @interface I + (void)foo; @end
+
+The matcher objcMethodDecl(isInstanceMethod())
+matches @interface I - (void)bar; @end
+but does not match @interface I - (void)foo; @end
+
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>></td><td class="name" onclick="toggle('hasDefaultArgument0')"><a name="hasDefaultArgument0Anchor">hasDefaultArgument</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasDefaultArgument0"><pre>Matches a declaration that has default arguments.
 
-Example matches y (matcher = parmVarDecl(hasDefaultArgument()))
-void x(int val) {}
-void y(int val = 0) {}
+Given
+  void x(int val) {}
+  void y(int val = 0) {}
+
+
+The matcher parmVarDecl(hasDefaultArgument())
+matches int val = 0.
 
 Deprecated. Use hasInitializer() instead to be able to
 match on the contents of the default argument.  For example:
 
-void x(int val = 7) {}
-void y(int val = 42) {}
-parmVarDecl(hasInitializer(integerLiteral(equals(42))))
-  matches the parameter of y
+Given
+  void x(int val = 7) {}
+  void y(int val = 42) {}
+
 
-A matcher such as
-  parmVarDecl(hasInitializer(anything()))
-is equivalent to parmVarDecl(hasDefaultArgument()).
+The matcher
+parmVarDecl(hasInitializer(integerLiteral(equals(42)))),
+matches int val = 42.
 </pre></td></tr>
 
 
@@ -5326,9 +7206,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 void f(int a, int b, int c) {
 }
 
-``parmVarDecl(isAtPosition(0))`` matches ``int a``.
-
-``parmVarDecl(isAtPosition(1))`` matches ``int b``.
+The matcher parmVarDecl(isAtPosition(0)) matches
+a. The matcher parmVarDecl(isAtPosition(1))
+matches b.
 </pre></td></tr>
 
 
@@ -5338,8 +7218,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   class Y { public: void x(); };
   void z() { Y* y; y->x(); }
-cxxMemberCallExpr(on(hasType(asString("class Y *"))))
-  matches y->x()
+
+The matcher cxxMemberCallExpr(on(hasType(asString("Y *"))))
+matches y->x()
 </pre></td></tr>
 
 
@@ -5350,10 +7231,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
   class X { int a; int b; };
-cxxRecordDecl(
+
+The matcher cxxRecordDecl(
     has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
     has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
-  matches the class X, as a and b have the same type.
+  matches X, as a and b have the same type.
 
 Note that when multiple matches are involved via forEach* matchers,
 equalsBoundNodes acts as a filter.
@@ -5372,12 +7254,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
   typedef const int const_int;
-  const_int i;
-  int *const j;
+  const_int i = 0;
+  int *const j = nullptr;
   int *volatile k;
   int m;
-varDecl(hasType(hasLocalQualifiers())) matches only j and k.
-i is const-qualified but the qualifier is not local.
+
+
+The matcher varDecl(hasType(hasLocalQualifiers())) matches only
+j and k. is
+const-qualified but the qualifier is not local.
 </pre></td></tr>
 
 
@@ -5388,9 +7273,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void a(char);
   void b(wchar_t);
   void c(double);
+
+
+The matcher
 functionDecl(hasAnyParameter(hasType(isAnyCharacter())))
-matches "a(char)", "b(wchar_t)", but not "c(double)".
-</pre></td></tr>
+a, b, but not </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('isAnyPointer0')"><a name="isAnyPointer0Anchor">isAnyPointer</a></td><td></td></tr>
@@ -5406,8 +7293,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   Foo *f;
 
   int j;
-varDecl(hasType(isAnyPointer()))
-  matches "int *i" and "Foo *f", but not "int j".
+
+The matcher varDecl(hasType(isAnyPointer()))
+int *i and Foo *f, but not int j.
 </pre></td></tr>
 
 
@@ -5421,9 +7309,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void c(const int);
   void d(const int*);
   void e(int const) {};
+The matcher
 functionDecl(hasAnyParameter(hasType(isConstQualified())))
-  matches "void b(int const)", "void c(const int)" and
-  "void e(int const) {}". It does not match d as there
+  matches b, c and
+  e.
+  It does not match as there
   is no top-level const on the parameter type "const int *".
 </pre></td></tr>
 
@@ -5435,8 +7325,8 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void a(int);
   void b(long);
   void c(double);
-functionDecl(hasAnyParameter(hasType(isInteger())))
-matches "a(int)", "b(long)", but not "c(double)".
+The matcher functionDecl(hasAnyParameter(hasType(isInteger())))
+a, b, but not c.
 </pre></td></tr>
 
 
@@ -5447,8 +7337,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void a(int);
   void b(unsigned long);
   void c(double);
-functionDecl(hasAnyParameter(hasType(isSignedInteger())))
-matches "a(int)", but not "b(unsigned long)" and "c(double)".
+The matcher
+functionDecl(hasAnyParameter(hasType(isSignedInteger()))) matches
+a, but not and not
 </pre></td></tr>
 
 
@@ -5459,8 +7350,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void a(int);
   void b(unsigned long);
   void c(double);
+The matcher
 functionDecl(hasAnyParameter(hasType(isUnsignedInteger())))
-matches "b(unsigned long)", but not "a(int)" and "c(double)".
+matches b,
+but does not match a and c.
 </pre></td></tr>
 
 
@@ -5474,9 +7367,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   void c(volatile int);
   void d(volatile int*);
   void e(int volatile) {};
+The matcher
 functionDecl(hasAnyParameter(hasType(isVolatileQualified())))
-  matches "void b(int volatile)", "void c(volatile int)" and
-  "void e(int volatile) {}". It does not match d as there
+  matches b, c and
+  e.
+  It does not match as there
   is no top-level volatile on the parameter type "volatile int *".
 </pre></td></tr>
 
@@ -5488,10 +7383,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
   class X { int a; int b; };
-cxxRecordDecl(
+
+The matcher cxxRecordDecl(
     has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
     has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
-  matches the class X, as a and b have the same type.
+  matches X, as a and b have the same type.
 
 Note that when multiple matches are involved via forEach* matchers,
 equalsBoundNodes acts as a filter.
@@ -5504,7 +7400,7 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 </pre></td></tr>
 
 
-<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsNode1')"><a name="equalsNode1Anchor">equalsNode</a></td><td>const Stmt* Other</td></tr>
+<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsNode1')"><a name="equalsNode1Anchor">equalsNode</a></td><td>const Stmt * Other</td></tr>
 <tr><td colspan="4" class="doc" id="equalsNode1"><pre>Matches if a node equals another node.
 
 Stmt has pointer identity in the AST.
@@ -5516,6 +7412,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Does not match if only part of the statement is expanded from that macro or
 if different parts of the statement are expanded from different
 appearances of the macro.
+
+Given
+  #define A 0
+  #define B A
+  int c = B;
+
+The matcher integerLiteral(isExpandedFromMacro("A"))
+matches the literal expanded at the initializer B of the variable
+c .
 </pre></td></tr>
 
 
@@ -5523,12 +7428,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isExpansionInFileMatching1"><pre>Matches AST nodes that were expanded within files whose name is
 partially matching a given regex.
 
-Example matches Y but not X
-    (matcher = cxxRecordDecl(isExpansionInFileMatching("AST.*"))
-  #include "ASTMatcher.h"
-  class X {};
-ASTMatcher.h:
-  class Y {};
+Given the headers Y.h
+  #pragma once
+  typedef int my_y_int;
+and X.h
+  #pragma once
+  typedef int my_x_int;
+and the source code
+  #include "X.h"
+  #include "Y.h"
+  typedef int my_main_file_int;
+  my_main_file_int a = 0;
+  my_x_int b = 1;
+  my_y_int c = 2;
+
+The matcher
+typedefDecl(isExpansionInFileMatching("Y.h"))
+matches typedef int my_y_int,
+but does not match typedef int my_main_file_int or
+typedef int my_x_int.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 
@@ -5541,12 +7459,18 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('isExpansionInMainFile1')"><a name="isExpansionInMainFile1Anchor">isExpansionInMainFile</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isExpansionInMainFile1"><pre>Matches AST nodes that were expanded within the main-file.
 
-Example matches X but not Y
-  (matcher = cxxRecordDecl(isExpansionInMainFile())
-  #include <Y.h>
-  class X {};
-Y.h:
-  class Y {};
+Given the header Y.h
+  #pragma once
+  typedef int my_header_int;
+and the source file
+  #include "Y.h"
+  typedef int my_main_file_int;
+  my_main_file_int a = 0;
+  my_header_int b = 1;
+
+The matcher typedefDecl(isExpansionInMainFile())
+matches typedef int my_main_file_int,
+but does not match typedef int my_header_int.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 </pre></td></tr>
@@ -5555,12 +7479,17 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('isExpansionInSystemHeader1')"><a name="isExpansionInSystemHeader1Anchor">isExpansionInSystemHeader</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isExpansionInSystemHeader1"><pre>Matches AST nodes that were expanded within system-header-files.
 
-Example matches Y but not X
-    (matcher = cxxRecordDecl(isExpansionInSystemHeader())
+Given the header SystemHeader.h
+  #pragma once
+  int header();
+and the source code
   #include <SystemHeader.h>
-  class X {};
-SystemHeader.h:
-  class Y {};
+  static int main_file();
+
+
+The matcher functionDecl(isExpansionInSystemHeader())
+matches int header(),
+but does not match static int main_file().
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 </pre></td></tr>
@@ -5571,14 +7500,18 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
   int j;
-  template<typename T> void A(T t) { T i; j += 42;}
-  A(0);
-  A(0U);
-declStmt(isInTemplateInstantiation())
-  matches 'int i;' and 'unsigned i'.
-unless(stmt(isInTemplateInstantiation()))
-  will NOT match j += 42; as it's shared between the template definition and
-  instantiation.
+  template<typename T> void A(T t) { T i; }
+  void foo() {
+    A(0);
+    A(0U);
+  }
+
+The matcher declStmt(isInTemplateInstantiation())
+matches T i; twice, once for int and once for
+int}.
+The matcher declStmt(unless(isInTemplateInstantiation())) will
+match T i; once inside the template definition, but not for any of
+the instantiated bodies.
 </pre></td></tr>
 
 
@@ -5592,21 +7525,28 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   char *s = "abcd";
   wchar_t *ws = L"abcd";
   char *w = "a";
-constantArrayType(hasSize(42))
-  matches "int a[42]" and "int b[2 * 21]"
-stringLiteral(hasSize(4))
-  matches "abcd", L"abcd"
+
+The matcher constantArrayType(hasSize(42))
+matches int[42] twice.
+The matcher stringLiteral(hasSize(4))
+matches "abcd" and L"abcd".
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>></td><td class="name" onclick="toggle('isClass0')"><a name="isClass0Anchor">isClass</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isClass0"><pre>Matches TagDecl object that are spelled with "class."
 
-Example matches C, but not S, U or E.
+Given
   struct S {};
   class C {};
   union U {};
-  enum E {};
+  enum E { Ok };
+
+The matcher tagDecl(isClass())
+matches class C,
+but does not match struct S,
+union U
+or enum E.
 </pre></td></tr>
 
 
@@ -5620,6 +7560,14 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   extern int vb;  // Doesn't match, as it doesn't define the variable.
   void fa() {}
   void fb();  // Doesn't match, as it has no body.
+
+The matcher tagDecl(isDefinition())
+matches A
+The matcher varDecl(isDefinition())
+matches va
+The matcher functionDecl(isDefinition())
+matches fa
+
   @interface X
   - (void)ma; // Doesn't match, interface is declaration.
   @end
@@ -5627,6 +7575,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   - (void)ma {}
   @end
 
+The matcher objcMethodDecl(isDefinition())
+matches - (void)ma {}
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>>
 </pre></td></tr>
@@ -5635,11 +7586,16 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>></td><td class="name" onclick="toggle('isEnum0')"><a name="isEnum0Anchor">isEnum</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isEnum0"><pre>Matches TagDecl object that are spelled with "enum."
 
-Example matches E, but not C, S or U.
+Given
   struct S {};
   class C {};
   union U {};
-  enum E {};
+  enum E { Ok };
+
+The matcher tagDecl(isEnum())
+matches enum E { Ok },
+but does not match struct S {},
+class C {} or union U {}.
 </pre></td></tr>
 
 
@@ -5650,18 +7606,30 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   struct S {};
   class C {};
   union U {};
-  enum E {};
+  enum E { Ok };
+
+The matcher tagDecl(isStruct())
+matches struct S,
+but does not match class C,
+union U
+or enum E.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>></td><td class="name" onclick="toggle('isUnion0')"><a name="isUnion0Anchor">isUnion</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isUnion0"><pre>Matches TagDecl object that are spelled with "union."
 
-Example matches U, but not C, S or E.
+Given
   struct S {};
   class C {};
   union U {};
-  enum E {};
+  enum E { Ok };
+
+The matcher tagDecl(isUnion())
+matches union U,
+does not match struct S,
+class C
+or enum E.
 </pre></td></tr>
 
 
@@ -5675,9 +7643,12 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   template<int T> struct C {};
   C<42> c;
-classTemplateSpecializationDecl(
+
+The matcher classTemplateSpecializationDecl(
   hasAnyTemplateArgument(equalsIntegralValue("42")))
-  matches the implicit instantiation of C in C<42>.
+matches the implicitly declared specialization
+struct C<42> from the instantiation for the type of the
+variable c .
 </pre></td></tr>
 
 
@@ -5687,10 +7658,12 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   template<int T> struct C {};
   C<42> c;
-classTemplateSpecializationDecl(
+
+The matcher classTemplateSpecializationDecl(
   hasAnyTemplateArgument(isIntegral()))
-  matches the implicit instantiation of C in C<42>
-  with isIntegral() matching 42.
+matches the implicitly declared specialization
+struct C<42> from the instantiation for the type of the
+variable c .
 </pre></td></tr>
 
 
@@ -5700,8 +7673,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   template<typename T> struct C {};
   C<int> c;
+
+The matcher
 classTemplateSpecializationDecl(templateArgumentCountIs(1))
-  matches C<int>.
+matches struct C<int>.
 </pre></td></tr>
 
 
@@ -5710,6 +7685,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Does not match if only part of the statement is expanded from that macro or
 if different parts of the statement are expanded from different
 appearances of the macro.
+
+Given
+  #define A 0
+  #define B A
+  int c = B;
+
+The matcher integerLiteral(isExpandedFromMacro("A"))
+matches the literal expanded at the initializer B of the variable
+c .
 </pre></td></tr>
 
 
@@ -5717,12 +7701,25 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isExpansionInFileMatching2"><pre>Matches AST nodes that were expanded within files whose name is
 partially matching a given regex.
 
-Example matches Y but not X
-    (matcher = cxxRecordDecl(isExpansionInFileMatching("AST.*"))
-  #include "ASTMatcher.h"
-  class X {};
-ASTMatcher.h:
-  class Y {};
+Given the headers Y.h
+  #pragma once
+  typedef int my_y_int;
+and X.h
+  #pragma once
+  typedef int my_x_int;
+and the source code
+  #include "X.h"
+  #include "Y.h"
+  typedef int my_main_file_int;
+  my_main_file_int a = 0;
+  my_x_int b = 1;
+  my_y_int c = 2;
+
+The matcher
+typedefDecl(isExpansionInFileMatching("Y.h"))
+matches typedef int my_y_int,
+but does not match typedef int my_main_file_int or
+typedef int my_x_int.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 
@@ -5735,12 +7732,18 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td><td class="name" onclick="toggle('isExpansionInMainFile2')"><a name="isExpansionInMainFile2Anchor">isExpansionInMainFile</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isExpansionInMainFile2"><pre>Matches AST nodes that were expanded within the main-file.
 
-Example matches X but not Y
-  (matcher = cxxRecordDecl(isExpansionInMainFile())
-  #include <Y.h>
-  class X {};
-Y.h:
-  class Y {};
+Given the header Y.h
+  #pragma once
+  typedef int my_header_int;
+and the source file
+  #include "Y.h"
+  typedef int my_main_file_int;
+  my_main_file_int a = 0;
+  my_header_int b = 1;
+
+The matcher typedefDecl(isExpansionInMainFile())
+matches typedef int my_main_file_int,
+but does not match typedef int my_header_int.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 </pre></td></tr>
@@ -5749,12 +7752,17 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td><td class="name" onclick="toggle('isExpansionInSystemHeader2')"><a name="isExpansionInSystemHeader2Anchor">isExpansionInSystemHeader</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isExpansionInSystemHeader2"><pre>Matches AST nodes that were expanded within system-header-files.
 
-Example matches Y but not X
-    (matcher = cxxRecordDecl(isExpansionInSystemHeader())
+Given the header SystemHeader.h
+  #pragma once
+  int header();
+and the source code
   #include <SystemHeader.h>
-  class X {};
-SystemHeader.h:
-  class Y {};
+  static int main_file();
+
+
+The matcher functionDecl(isExpansionInSystemHeader())
+matches int header(),
+but does not match static int main_file().
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>
 </pre></td></tr>
@@ -5765,8 +7773,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
  struct S { bool func(); };
-functionDecl(returns(booleanType()))
-  matches "bool func();"
+
+The matcher functionDecl(returns(booleanType()))
+func
 </pre></td></tr>
 
 
@@ -5777,10 +7786,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
   class X { int a; int b; };
-cxxRecordDecl(
+
+The matcher cxxRecordDecl(
     has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
     has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
-  matches the class X, as a and b have the same type.
+  matches X, as a and b have the same type.
 
 Note that when multiple matches are involved via forEach* matchers,
 equalsBoundNodes acts as a filter.
@@ -5793,7 +7803,7 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 </pre></td></tr>
 
 
-<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('equalsNode2')"><a name="equalsNode2Anchor">equalsNode</a></td><td>const Type* Other</td></tr>
+<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('equalsNode2')"><a name="equalsNode2Anchor">equalsNode</a></td><td>const Type * Other</td></tr>
 <tr><td colspan="4" class="doc" id="equalsNode2"><pre>Matches if a node equals another node.
 
 Type has pointer identity in the AST.
@@ -5806,8 +7816,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   int i;
   float f;
-realFloatingPointType()
-  matches "float f" but not "int i"
+The matcher type(realFloatingPointType())
+matches float
+but does not match int.
 </pre></td></tr>
 
 
@@ -5816,8 +7827,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
  struct S { void func(); };
-functionDecl(returns(voidType()))
-  matches "void func();"
+
+
+The matcher functionDecl(returns(voidType()))
+func
 </pre></td></tr>
 
 
@@ -5826,9 +7839,10 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 
 Given
   int x;
-  int s = sizeof(x) + alignof(x)
-unaryExprOrTypeTraitExpr(ofKind(UETT_SizeOf))
-  matches sizeof(x)
+  int s = sizeof(x) + alignof(x);
+
+The matcher unaryExprOrTypeTraitExpr(ofKind(UETT_SizeOf))
+matches sizeof(x)
 
 If the matcher is use from clang-query, UnaryExprOrTypeTrait parameter
 should be passed as a quoted string. e.g., ofKind("UETT_SizeOf").
@@ -5839,9 +7853,26 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasAnyOperatorName3"><pre>Matches operator expressions (binary or unary) that have any of the
 specified names.
 
+It provides a compact way of writing if an operator has any of the specified
+names:
+The matcher
    hasAnyOperatorName("+", "-")
- Is equivalent to
-   anyOf(hasOperatorName("+"), hasOperatorName("-"))
+Is equivalent to
+   hasOperatorName("-"))}
+
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+void bar(bool a, bool b) {
+  a && b;
+ }
+
+The matcher binaryOperator(hasAnyOperatorName("||", "&&"))
+matches a || b and a && b.
+The matcher unaryOperator(hasAnyOperatorName("-", "!"))
+matches !(a || b).
 </pre></td></tr>
 
 
@@ -5849,15 +7880,22 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperatorName4"><pre>Matches the operator Name of operator expressions and fold expressions
 (binary or unary).
 
-Example matches a || b (matcher = binaryOperator(hasOperatorName("||")))
-  !(a || b)
+Given
+void foo(bool a, bool b) {
+  !(a || b);
+ }
+
+The matcher binaryOperator(hasOperatorName("||"))
+matches a || b
 
-Example matches `(0 + ... + args)`
-    (matcher = cxxFoldExpr(hasOperatorName("+")))
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
   }
+
+The matcher cxxFoldExpr(hasOperatorName("+"))
+ matches (0 + ... + args).
 </pre></td></tr>
 
 
@@ -5876,40 +7914,57 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   };
   template <class T>
   class Z {
-    void x() { this->m; }
+    void x() {
+      this->m;
+      this->t;
+      this->t->m;
+    }
+    int m;
+    T* t;
   };
-memberExpr(isArrow())
-  matches this->x, x, y.x, a, this->b
-cxxDependentScopeMemberExpr(isArrow())
-  matches this->m
-unresolvedMemberExpr(isArrow())
-  matches this->f<T>, f<T>
+
+The matcher memberExpr(isArrow())
+matches this->x, x, a,
+this->b, this->m and two times this->t,
+once for the standalone member expression, and once for the member
+expression that later accesses m .
+Additionally, it does not match this->t->t.
+The matcher cxxDependentScopeMemberExpr(isArrow())
+matches this->t->m, but not this->m or this->t.
+The matcher unresolvedMemberExpr(isArrow())
+matches this->f<T>, f<T>
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('hasAutomaticStorageDuration0')"><a name="hasAutomaticStorageDuration0Anchor">hasAutomaticStorageDuration</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasAutomaticStorageDuration0"><pre>Matches a variable declaration that has automatic storage duration.
 
-Example matches x, but not y, z, or a.
-(matcher = varDecl(hasAutomaticStorageDuration())
+Given
 void f() {
   int x;
   static int y;
   thread_local int z;
 }
 int a;
+
+The matcher varDecl(hasAutomaticStorageDuration())
+matches x
+but does not match y, z or
+a
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('hasGlobalStorage0')"><a name="hasGlobalStorage0Anchor">hasGlobalStorage</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasGlobalStorage0"><pre>Matches a variable declaration that does not have local storage.
 
-Example matches y and z (matcher = varDecl(hasGlobalStorage())
+Given
 void f() {
   int x;
   static int y;
 }
 int z;
+The matcher varDecl(hasGlobalStorage())
+matches y and z
 </pre></td></tr>
 
 
@@ -5917,12 +7972,14 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasLocalStorage0"><pre>Matches a variable declaration that has function scope and is a
 non-static local variable.
 
-Example matches x (matcher = varDecl(hasLocalStorage())
+Given
 void f() {
   int x;
   static int y;
 }
 int z;
+The matcher varDecl(hasLocalStorage())
+matches x
 </pre></td></tr>
 
 
@@ -5939,22 +7996,28 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 int a;
 static int b;
 extern int c;
-varDecl(hasStaticStorageDuration())
-  matches the function declaration y, a, b and c.
+
+The matcher varDecl(hasStaticStorageDuration())
+matches y, a, b and
+c
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('hasThreadStorageDuration0')"><a name="hasThreadStorageDuration0Anchor">hasThreadStorageDuration</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasThreadStorageDuration0"><pre>Matches a variable declaration that has thread storage duration.
 
-Example matches z, but not x, z, or a.
-(matcher = varDecl(hasThreadStorageDuration())
+Given
 void f() {
   int x;
   static int y;
   thread_local int z;
 }
 int a;
+
+The matcher varDecl(hasThreadStorageDuration())
+matches z
+but does not match x, z or
+a
 </pre></td></tr>
 
 
@@ -5962,29 +8025,34 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isConstexpr0"><pre>Matches constexpr variable and function declarations,
        and if constexpr.
 
-Given:
+Given
   constexpr int foo = 42;
   constexpr int bar();
   void baz() { if constexpr(1 > 0) {} }
-varDecl(isConstexpr())
-  matches the declaration of foo.
-functionDecl(isConstexpr())
-  matches the declaration of bar.
-ifStmt(isConstexpr())
-  matches the if statement in baz.
+
+The matcher varDecl(isConstexpr())
+matches foo.
+The matcher functionDecl(isConstexpr())
+matches bar.
+The matcher ifStmt(isConstexpr())
+matches if constexpr(1 > 0) {}.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('isConstinit0')"><a name="isConstinit0Anchor">isConstinit</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isConstinit0"><pre>Matches constinit variable declarations.
 
-Given:
+Given
   constinit int foo = 42;
   constinit const char* bar = "bar";
   int baz = 42;
   [[clang::require_constant_initialization]] int xyz = 42;
-varDecl(isConstinit())
-  matches the declaration of `foo` and `bar`, but not `baz` and `xyz`.
+
+The matcher varDecl(isConstinit())
+matches the declaration of foo
+and bar,
+but does not match baz or
+xyz.
 </pre></td></tr>
 
 
@@ -5998,6 +8066,14 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   extern int vb;  // Doesn't match, as it doesn't define the variable.
   void fa() {}
   void fb();  // Doesn't match, as it has no body.
+
+The matcher tagDecl(isDefinition())
+matches A
+The matcher varDecl(isDefinition())
+matches va
+The matcher functionDecl(isDefinition())
+matches fa
+
   @interface X
   - (void)ma; // Doesn't match, interface is declaration.
   @end
@@ -6005,6 +8081,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   - (void)ma {}
   @end
 
+The matcher objcMethodDecl(isDefinition())
+matches - (void)ma {}
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagDecl.html">TagDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>>
 </pre></td></tr>
@@ -6014,12 +8093,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isExceptionVariable0"><pre>Matches a variable declaration that is an exception variable from
 a C++ catch block, or an Objective-C statement.
 
-Example matches x (matcher = varDecl(isExceptionVariable())
+Given
 void f(int y) {
   try {
   } catch (int x) {
   }
 }
+
+The matcher varDecl(isExceptionVariable())
+matches x
 </pre></td></tr>
 
 
@@ -6030,8 +8112,9 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 Given
   template<typename T> void A(T t) { }
   template<> void A(int N) { }
-functionDecl(isExplicitTemplateSpecialization())
-  matches the specialization A<int>().
+
+The matcher functionDecl(isExplicitTemplateSpecialization())
+  matches the specialization template<> void A(int N) { }.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
 </pre></td></tr>
@@ -6040,17 +8123,21 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('isExternC1')"><a name="isExternC1Anchor">isExternC</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isExternC1"><pre>Matches extern "C" function or variable declarations.
 
-Given:
+Given
   extern "C" void f() {}
   extern "C" { void g() {} }
   void h() {}
   extern "C" int x = 1;
   extern "C" int y = 2;
   int z = 3;
-functionDecl(isExternC())
-  matches the declaration of f and g, but not the declaration of h.
-varDecl(isExternC())
-  matches the declaration of x and y, but not the declaration of z.
+
+The matcher functionDecl(isExternC())
+matches f
+and g.
+The matcher varDecl(isExternC())
+matches x
+and y,
+but does not match z.
 </pre></td></tr>
 
 
@@ -6058,8 +8145,11 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isInitCapture0"><pre>Matches a variable serving as the implicit variable for a lambda init-
 capture.
 
-Example matches x (matcher = varDecl(isInitCapture()))
-auto f = [x=3]() { return x; };
+Given
+auto f = [x = 3]() { return x; };
+
+The matcher varDecl(isInitCapture())
+matches x = 3.
 </pre></td></tr>
 
 
@@ -6074,21 +8164,24 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
   inline namespace m {}
   }
   inline int Foo = 5;
-functionDecl(isInline()) will match ::f().
-namespaceDecl(isInline()) will match n::m.
-varDecl(isInline()) will match Foo;
+
+The matcher functionDecl(isInline()) matches f.
+The matcher namespaceDecl(isInline()) matches m.
+The matcher varDecl(isInline()) matches Foo
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('isStaticLocal0')"><a name="isStaticLocal0Anchor">isStaticLocal</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isStaticLocal0"><pre>Matches a static variable with local scope.
 
-Example matches y (matcher = varDecl(isStaticLocal()))
+Given
 void f() {
   int x;
   static int y;
 }
 static int z;
+The matcher varDecl(isStaticLocal())
+matches y
 </pre></td></tr>
 
 
@@ -6096,15 +8189,15 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 <tr><td colspan="4" class="doc" id="isStaticStorageClass1"><pre>Matches variable/function declarations that have "static" storage
 class specifier ("static" keyword) written in the source.
 
-Given:
+Given
   static void f() {}
   static int i = 0;
   extern int j;
   int k;
-functionDecl(isStaticStorageClass())
-  matches the function declaration f.
-varDecl(isStaticStorageClass())
-  matches the variable declaration i.
+The matcher functionDecl(isStaticStorageClass())
+  matches f
+The matcher varDecl(isStaticStorageClass())
+  matches i
 </pre></td></tr>
 
 
@@ -6113,18 +8206,36 @@ <h2 id="narrowing-matchers">Narrowing Matchers</h2>
 member variable template instantiations.
 
 Given
-  template <typename T> class X {}; class A {}; X<A> x;
-or
-  template <typename T> class X {}; class A {}; template class X<A>;
-or
-  template <typename T> class X {}; class A {}; extern template class X<A>;
-cxxRecordDecl(hasName("::X"), isTemplateInstantiation())
-  matches the template instantiation of X<A>.
+  template <typename T> class X {};
+  class A {};
+  X<A> x;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches class X<class A>.
+  template <typename T> class X {};
+  class A {};
+  template class X<A>;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches template class X<A>
+  template <typename T> class X {};
+  class A {};
+  extern template class X<A>;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
+matches extern template class X<A>
 
 But given
-  template <typename T>  class X {}; class A {};
-  template <> class X<A> {}; X<A> x;
-cxxRecordDecl(hasName("::X"), isTemplateInstantiation())
+  template <typename T>  class X {};
+  class A {};
+  template <> class X<A> {};
+  X<A> x;
+
+The matcher cxxRecordDecl(hasName("::X"),
+isTemplateInstantiation())
   does not match, as X<A> is an explicit template specialization.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>
@@ -6151,10 +8262,9 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<*></td><td class="name" onclick="toggle('binaryOperation0')"><a name="binaryOperation0Anchor">binaryOperation</a></td><td>Matcher<*>...Matcher<*></td></tr>
 <tr><td colspan="4" class="doc" id="binaryOperation0"><pre>Matches nodes which can be used with binary operators.
 
-The code
-  var1 != var2;
-might be represented in the clang AST as a binaryOperator, a
-cxxOperatorCallExpr or a cxxRewrittenBinaryOperator, depending on
+A comparison of two expressions might be represented in the clang AST as a
+binaryOperator, a cxxOperatorCallExpr or a
+cxxRewrittenBinaryOperator, depending on
 
 * whether the types of var1 and var2 are fundamental (binaryOperator) or at
   least one is a class type (cxxOperatorCallExpr)
@@ -6168,12 +8278,6 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 compatible.
 
 Given
-  binaryOperation(
-    hasOperatorName("!="),
-    hasLHS(expr().bind("lhs")),
-    hasRHS(expr().bind("rhs"))
-  )
-matches each use of "!=" in:
   struct S{
       bool operator!=(const S&) const;
   };
@@ -6187,25 +8291,28 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<typename T>
   void templ()
   {
-     1 != 2;
+     3 != 4;
      T() != S();
   }
   struct HasOpEq
   {
-      bool operator==(const HasOpEq &) const;
+      friend bool
+      operator==(const HasOpEq &, const HasOpEq&) noexcept = default;
   };
 
   void inverse()
   {
-      HasOpEq s1;
-      HasOpEq s2;
-      if (s1 != s2)
+      HasOpEq e1;
+      HasOpEq e2;
+      if (e1 != e2)
           return;
   }
 
   struct HasSpaceship
   {
-      bool operator<=>(const HasOpEq &) const;
+      friend bool
+      operator<=>(const HasSpaceship &,
+                  const HasSpaceship&) noexcept = default;
   };
 
   void use_spaceship()
@@ -6215,6 +8322,15 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
       if (s1 != s2)
           return;
   }
+
+
+The matcher binaryOperation(
+    hasOperatorName("!="),
+    hasLHS(expr().bind("lhs")),
+    hasRHS(expr().bind("rhs"))
+  )
+matches 1 != 2, S() != S(), 3 != 4,
+T() != S(), e1 != e2 and s1 != s2.
 </pre></td></tr>
 
 
@@ -6224,14 +8340,18 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Unlike anyOf, eachOf will generate a match result for each
 matching submatcher.
 
-For example, in:
-  class A { int a; int b; };
-The matcher:
-  cxxRecordDecl(eachOf(has(fieldDecl(hasName("a")).bind("v")),
-                       has(fieldDecl(hasName("b")).bind("v"))))
-will generate two results binding "v", the first of which binds
-the field declaration of a, the second the field declaration of
-b.
+Given
+  void f(int a, int b);
+
+
+The matcher functionDecl(hasAnyParameter(
+eachOf(parmVarDecl(hasName("a")).bind("v"),
+       parmVarDecl(hasName("b")).bind("v"))))
+matches void f(int a, int b),
+with parmVarDecl(hasName("a")) matching a
+for one match,
+and with parmVarDecl(hasName("b")) matching
+b for the other match.
 
 Usable as: Any Matcher
 </pre></td></tr>
@@ -6244,10 +8364,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 For example, in:
   class A { class B {}; class C {}; };
-The matcher:
-  cxxRecordDecl(hasName("::A"),
+
+The matcher
+cxxRecordDecl(hasName("::A"),
                 findAll(cxxRecordDecl(isDefinition()).bind("m")))
-will generate results for A, B and C.
+matches A three times,
+with cxxRecordDecl(isDefinition()).bind("m")
+matching A,
+B and C.
 
 Usable as: Any Matcher
 </pre></td></tr>
@@ -6257,24 +8381,71 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <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, A::X, B, B::C, B::C::X
-  (matcher = cxxRecordDecl(forEachDescendant(cxxRecordDecl(hasName("X")))))
+Given
   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 {}; }; };
 
+The matcher
+cxxRecordDecl(forEachDescendant(cxxRecordDecl(hasName("X"))))
+matches X, A,
+B, class B::C
+and class B::C::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 {}; }; }; }; };
+  struct A {
+    struct B {
+      struct C {};
+      struct D {};
+    };
+  };
+
+
+The matcher cxxRecordDecl(forEachDescendant(cxxRecordDecl(
+    forEachDescendant(cxxRecordDecl().bind("inner"))
+  ).bind("middle")))
+will match 9 times:
+It matches the definition of A with the definition of
+B in the middle and the injected class name of
+B as the innermost cxxRecordDecl.
+
+It matches the definition of A with the definition of
+C in the middle and the definition of
+B as the innermost cxxRecordDecl.
+
+It matches the definition of A with the definition of
+C in the middle and the injected class name of
+B as the innermost cxxRecordDecl.
+
+It matches the definition of A with the definition of
+B in the middle and the definition of
+D as the innermost cxxRecordDecl.
+
+It matches the definition of A with the definition of
+B in the middle and the injected class name of
+D as the innermost cxxRecordDecl.
+
+It matches the definition of A with the definition of
+C in the middle and the injected class name of
+C as the innermost cxxRecordDecl.
+
+It matches the definition of A with the definition of
+D in the middle and the injected class name of
+D as the innermost cxxRecordDecl.
+
+It matches the definition of B with the definition of
+C in the middle and the injected class name of
+C as the innermost cxxRecordDecl.
+
+It matches the definition of B with the definition of
+D in the middle and the injected class name of
+D as the innermost cxxRecordDecl.
 
 Usable as: Any Matcher
 </pre></td></tr>
@@ -6284,17 +8455,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <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, Y::X, Z::Y, Z::Y::X
-  (matcher = cxxRecordDecl(forEach(cxxRecordDecl(hasName("X")))
+Given
   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.
 
+The matcher cxxRecordDecl(forEach(cxxRecordDecl(hasName("X"))))
+matches class X,
+class Y,
+class Y::X,
+class Z::Y::X and class Z::Y
+
 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.
+  matches instead of only on the first one.
 
 Usable as: Any Matcher
 </pre></td></tr>
@@ -6307,7 +8483,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
 void f() { if (true) { int x = 42; } }
 void g() { for (;;) { int x = 43; } }
-expr(integerLiteral(hasAncestor(ifStmt()))) matches 42, but not 43.
+
+The matcher expr(integerLiteral(hasAncestor(ifStmt())))
+matches 42
+but does not match 43
 
 Usable as: Any Matcher
 </pre></td></tr>
@@ -6317,12 +8496,16 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasDescendant0"><pre>Matches AST nodes that have descendant AST nodes that match the
 provided matcher.
 
-Example matches X, Y, Z
-    (matcher = cxxRecordDecl(hasDescendant(cxxRecordDecl(hasName("X")))))
+Given
   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 {}; }; };
 
+The matcher
+cxxRecordDecl(hasDescendant(cxxRecordDecl(hasName("X"))))
+matches class X {}, class Y { class X {}; }
+and class Z { class Y { class X {}; }; }.
+
 DescendantT must be an AST base type.
 
 Usable as: Any Matcher
@@ -6333,19 +8516,29 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="has0"><pre>Matches AST nodes that have child AST nodes that match the
 provided matcher.
 
-Example matches X, Y
-  (matcher = cxxRecordDecl(has(cxxRecordDecl(hasName("X")))
+Given
   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.
 
+The matcher cxxRecordDecl(has(cxxRecordDecl(hasName("X"))))
+matches class X {} three times,
+and class Y { class X {}; } two times.
+
 ChildT must be an AST base type.
 
 Usable as: Any Matcher
 Note that has is direct matcher, so it also matches things like implicit
 casts and paren casts. If you are matching with expr then you should
-probably consider using ignoringParenImpCasts like:
-has(ignoringParenImpCasts(expr())).
+probably consider using ignoringParenImpCasts:
+
+Given
+  int x =0;
+  double y = static_cast<double>(x);
+
+The matcher
+cxxStaticCastExpr(has(ignoringParenImpCasts(declRefExpr()))).
+matches static_cast<double>(x)
 </pre></td></tr>
 
 
@@ -6355,7 +8548,9 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
 void f() { for (;;) { int x = 42; if (true) { int x = 43; } } }
-compoundStmt(hasParent(ifStmt())) matches "{ int x = 43; }".
+
+The matcher compoundStmt(hasParent(ifStmt()))
+matches { int x = 43; }
 
 Usable as: Any Matcher
 </pre></td></tr>
@@ -6369,7 +8564,7 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 which should match both are typically duplicated. This matcher
 removes the need for duplication.
 
-Given code
+Given
 struct ConstructorTakesInt
 {
   ConstructorTakesInt(int i) {}
@@ -6389,9 +8584,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   ConstructorTakesInt cti(42);
 }
 
+
 The matcher
-invocation(hasArgument(0, integerLiteral(equals(42))))
-matches the expression in both doCall and doConstruct
+expr(invocation(hasArgument(0, integerLiteral(equals(42)))))
+matches the expressions callTakesInt(42)
+and cti(42).
 </pre></td></tr>
 
 
@@ -6402,18 +8599,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Useful when additional information which may or may not present about a main
 matching node is desired.
 
-For example, in:
-  class Foo {
-    int bar;
-  }
-The matcher:
-  cxxRecordDecl(
-    optionally(has(
-      fieldDecl(hasName("bar")).bind("var")
-  ))).bind("record")
-will produce a result binding for both "record" and "var".
-The matcher will produce a "record" binding for even if there is no data
-member named "bar" in that class.
+Given
+  int a = 0;
+  int b;
+
+The matcher varDecl(optionally(hasInitializer(expr())))
+matches int a = 0 and int b.
 
 Usable as: Any Matcher
 </pre></td></tr>
@@ -6428,10 +8619,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
       int i = 3.0;
   }
 The matcher
-  traverse(TK_IgnoreUnlessSpelledInSource,
+traverse(TK_IgnoreUnlessSpelledInSource,
     varDecl(hasInitializer(floatLiteral().bind("init")))
   )
-matches the variable declaration with "init" bound to the "3.0".
+  matches int i = 3.0 with "init" bound to 3.0.
 </pre></td></tr>
 
 
@@ -6439,8 +8630,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasCondition5"><pre>Matches the condition expression of an if statement, for loop,
 switch statement or conditional operator.
 
-Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true))))
+Given
+void foo() {
   if (true) {}
+}
+
+The matcher ifStmt(hasCondition(cxxBoolLiteral(equals(true))))
+if (true) {}
 </pre></td></tr>
 
 
@@ -6449,8 +8645,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 (binary or ternary).
 
 Example matches b
-  condition ? a : b
-  condition ?: b
+  void foo(bool condition, int a, int b) {
+    condition ? a : b;
+    condition ?: b;
+  }
+
+The matcher
+conditionalOperator(hasFalseExpression(expr().bind("false")))
+matches condition ? a : b,
+with expr() matching b.
+The matcher
+binaryConditionalOperator(hasFalseExpression(expr().bind("false")))
+matches condition ?: b,
+with expr() matching b.
 </pre></td></tr>
 
 
@@ -6458,16 +8665,31 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasTrueExpression0"><pre>Matches the true branch expression of a conditional operator.
 
 Example 1 (conditional ternary operator): matches a
-  condition ? a : b
+Given
+  void foo(bool condition, int a, int b) {
+    condition ? a : b;
+  }
+
+The matcher
+conditionalOperator(hasTrueExpression(expr().bind("true")))
+matches condition ? a : b,
+with expr() matching a.
 
 Example 2 (conditional binary operator): matches opaqueValueExpr(condition)
-  condition ?: b
+Given
+  void foo(bool condition, int a, int b) {
+    condition ?: b;
+  }
+
+The matcher binaryConditionalOperator(hasTrueExpression(expr()))
+matches condition ?: b,
+with expr() matching conditoin.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>></td><td class="name" onclick="toggle('hasDeclaration15')"><a name="hasDeclaration15Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration15"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -6477,17 +8699,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -6505,7 +8735,7 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   int i[5];
   void f() { i[1] = 42; }
-arraySubscriptExpression(hasBase(implicitCastExpr(
+The matcher arraySubscriptExpr(hasBase(implicitCastExpr(
     hasSourceExpression(declRefExpr()))))
   matches i[1] with the declRefExpr() matching i
 </pre></td></tr>
@@ -6517,7 +8747,7 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   int i[5];
   void f() { i[1] = 42; }
-arraySubscriptExpression(hasIndex(integerLiteral()))
+The matcher arraySubscriptExpr(hasIndex(integerLiteral()))
   matches i[1] with the integerLiteral() matching 1
 </pre></td></tr>
 
@@ -6525,16 +8755,30 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ArraySubscriptExpr.html">ArraySubscriptExpr</a>></td><td class="name" onclick="toggle('hasLHS3')"><a name="hasLHS3Anchor">hasLHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasLHS3"><pre>Matches the left hand side of binary operator expressions.
 
-Example matches a (matcher = binaryOperator(hasLHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasLHS(expr().bind("lhs")))
+matches a || b,
+with expr()
+matching a.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ArraySubscriptExpr.html">ArraySubscriptExpr</a>></td><td class="name" onclick="toggle('hasRHS3')"><a name="hasRHS3Anchor">hasRHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasRHS3"><pre>Matches the right hand side of binary operator expressions.
 
-Example matches b (matcher = binaryOperator(hasRHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasRHS(expr().bind("rhs")))
+matches a || b,
+with expr()
+matching b.
 </pre></td></tr>
 
 
@@ -6546,8 +8790,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   struct A {};
   A a[7];
   int b[7];
-arrayType(hasElementType(builtinType()))
-  matches "int b[7]"
+
+
+The matcher arrayType(hasElementType(builtinType()))
+int[7]
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ArrayType.html">ArrayType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ComplexType.html">ComplexType</a>>
 </pre></td></tr>
@@ -6559,8 +8805,8 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   _Atomic(int) i;
   _Atomic(float) f;
-atomicType(hasValueType(isInteger()))
- matches "_Atomic(int) i"
+The matcher atomicType(hasValueType(isInteger()))
+_Atomic(int).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AtomicType.html">AtomicType</a>>
 </pre></td></tr>
@@ -6575,8 +8821,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   auto a = 1;
   auto b = 2.0;
-autoType(hasDeducedType(isInteger()))
-  matches "auto a"
+
+The matcher
+varDecl(hasType(autoType(hasDeducedType(isInteger()))))
+matches auto a = 1, but does not match auto b = 2.0.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AutoType.html">AutoType</a>>
 </pre></td></tr>
@@ -6588,21 +8836,54 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   namespace X { void b(); }
   using X::b;
-usingDecl(hasAnyUsingShadowDecl(hasName("b"))))
-  matches using X::b </pre></td></tr>
+
+The matcher usingDecl(hasAnyUsingShadowDecl(hasName("b")))
+  matches using X::b
+</pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasEitherOperand0')"><a name="hasEitherOperand0Anchor">hasEitherOperand</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasEitherOperand0"><pre>Matches if either the left hand side or the right hand side of a
 binary operator or fold expression matches.
+
+Given
+  struct S {};
+  bool operator ==(const S&, const S&);
+
+  void f(int a, const S&lhs, const S&rhs) {
+      a + 0;
+      lhs == rhs;
+      lhs != rhs;
+  }
+
+  template <typename ...Ts>
+  auto sum(Ts... args) {
+    return (0 + ... + args);
+  }
+
+
+The matcher binaryOperator(hasEitherOperand(integerLiteral()))
+matches a + 0.
+The matcher cxxOperatorCallExpr(hasEitherOperand(declRefExpr(to(
+parmVarDecl(hasName("lhs")))))) matches lhs == rhs and
+lhs != rhs.
+The matcher cxxFoldExpr(hasEitherOperand(integerLiteral()))
+matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasLHS0')"><a name="hasLHS0Anchor">hasLHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasLHS0"><pre>Matches the left hand side of binary operator expressions.
 
-Example matches a (matcher = binaryOperator(hasLHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasLHS(expr().bind("lhs")))
+matches a || b,
+with expr()
+matching a.
 </pre></td></tr>
 
 
@@ -6610,27 +8891,40 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperands0"><pre>Matches if both matchers match with opposite sides of the binary operator
 or fold expression.
 
-Example matcher = binaryOperator(hasOperands(integerLiteral(equals(1),
-                                             integerLiteral(equals(2)))
-  1 + 2 // Match
-  2 + 1 // Match
-  1 + 1 // No match
-  2 + 2 // No match
+Given
+void foo() {
+  1 + 2; // Match
+  2 + 1; // Match
+  1 + 1; // No match
+  2 + 2; // No match
+}
+The matcher binaryOperator(hasOperands(integerLiteral(equals(1)),
+                                            integerLiteral(equals(2))))
+matches 1 + 2 and 2 + 1,
+but does not match 1 + 1
+or 2 + 2.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasRHS0')"><a name="hasRHS0Anchor">hasRHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasRHS0"><pre>Matches the right hand side of binary operator expressions.
 
-Example matches b (matcher = binaryOperator(hasRHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasRHS(expr().bind("rhs")))
+matches a || b,
+with expr()
+matching b.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BindingDecl.html">BindingDecl</a>></td><td class="name" onclick="toggle('forDecomposition0')"><a name="forDecomposition0Anchor">forDecomposition</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="forDecomposition0"><pre>Matches the DecompositionDecl the binding belongs to.
 
-For example, in:
+Given
 void foo()
 {
     int arr[3];
@@ -6638,10 +8932,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
     f = 42;
 }
-The matcher:
-  bindingDecl(hasName("f"),
-                forDecomposition(decompositionDecl())
-matches 'f' in 'auto &[f, s, t]'.
+
+The matcher bindingDecl(hasName("f"),
+                forDecomposition(decompositionDecl()))
+matches f in 'auto &[f, s, t]'.
 </pre></td></tr>
 
 
@@ -6653,23 +8947,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   class X { void f(int x, int y, int z) {} };
-cxxMethodDecl(hasAnyParameter(hasName("y")))
-  matches f(int x, int y, int z) {}
+
+The matcher cxxMethodDecl(hasAnyParameter(hasName("y")))
+  matches f
 with hasAnyParameter(...)
   matching int y
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
 
+
 the matcher objcMethodDecl(hasAnyParameter(hasName("y")))
-matches the declaration of method f with hasParameter
+  matches the declaration of method f with hasParameter
 matching y.
 
 For blocks, given
   b = ^(int y) { printf("%d", y) };
 
+
 the matcher blockDecl(hasAnyParameter(hasName("y")))
-matches the declaration of the block b with hasParameter
+  matches the declaration of the block b with hasParameter
 matching y.
 </pre></td></tr>
 
@@ -6680,15 +8977,18 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   class X { void f(int x) {} };
-cxxMethodDecl(hasParameter(0, hasType(varDecl())))
-  matches f(int x) {}
+
+The matcher
+cxxMethodDecl(hasParameter(0, hasType(asString("int"))))
+matches f
 with hasParameter(...)
-  matching int x
+matching int x.
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
 
-the matcher objcMethodDecl(hasParameter(0, hasName("y")))
+
+The matcher objcMethodDecl(hasParameter(0, hasName("y")))
 matches the declaration of method f with hasParameter
 matching y.
 </pre></td></tr>
@@ -6697,19 +8997,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>></td><td class="name" onclick="toggle('hasTypeLoc0')"><a name="hasTypeLoc0Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc0"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -6728,10 +9035,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   int *a;
-  int const *b;
-  float const *f;
-pointerType(pointee(isConstQualified(), isInteger()))
-  matches "int const *b"
+  const int *b;
+  int * const c = nullptr;
+  const float *f;
+
+The matcher pointerType(pointee(isConstQualified(), isInteger()))
+matches const int *,
+but does not match int * const
+or const float *.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
@@ -6741,19 +9052,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>></td><td class="name" onclick="toggle('hasTypeLoc1')"><a name="hasTypeLoc1Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc1"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -6776,21 +9094,31 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 X, while varDecl(hasType(cxxRecordDecl(hasName("X")))) matches the
 declaration of x.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              cxxRecordDecl(hasName("X"))))
  class X {};
  void y(X &x) { x; X z; }
  class Y { friend class X; };
  class Z : public virtual X {};
 
-Example matches class Derived
-(matcher = cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base"))))))
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z.
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X.
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches
+class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
+
+Given
 class Base {};
 class Derived : Base {};
 
+The matcher
+cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base")))))
+matches class Derived : Base {}.
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FriendDecl.html">FriendDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>>,
 Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>
 </pre></td></tr>
@@ -6800,17 +9128,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasType4"><pre>Matches if the expression's or declaration's type matches a type
 matcher.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and U (matcher = typedefDecl(hasType(asString("int")))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              asString("class X")))
+Exmaple
  class X {};
  void y(X &x) { x; X z; }
  typedef int U;
  class Y { friend class X; };
  class Z : public virtual X {};
+
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z
+The matcher typedefDecl(hasType(asString("int")))
+matches typedef int U
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
 </pre></td></tr>
 
 
@@ -6820,8 +9156,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   void f(int i);
   int y;
-  f(y);
-callExpr(
+  void foo() {
+    f(y);
+  }
+The matcher callExpr(
   forEachArgumentWithParam(
     declRefExpr(to(varDecl(hasName("y")))),
     parmVarDecl(hasType(isInteger()))
@@ -6844,14 +9182,15 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   void f(int i);
-  int y;
-  f(y);
-  void (*f_ptr)(int) = f;
-  f_ptr(y);
-callExpr(
+  void foo(int y) {
+    f(y);
+    void (*f_ptr)(int) = f;
+    f_ptr(y);
+  }
+The matcher callExpr(
   forEachArgumentWithParamType(
     declRefExpr(to(varDecl(hasName("y")))),
-    qualType(isInteger()).bind("type)
+    qualType(isInteger()).bind("type")
 ))
   matches f(y) and f_ptr(y)
 with declRefExpr(...)
@@ -6866,17 +9205,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 expression, or an ObjC-message-send expression.
 
 Given
-  void x(int, int, int) { int y; x(1, y, 42); }
-callExpr(hasAnyArgument(declRefExpr()))
-  matches x(1, y, 42)
-with hasAnyArgument(...)
+  void x(int, int, int) { int y = 42; x(1, y, 42); }
+The matcher
+callExpr(hasAnyArgument(ignoringImplicit(declRefExpr()))) matches
+x(1, y, 42) with hasAnyArgument(...)
   matching y
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
   void foo(I *i) { [i f:12]; }
+
+The matcher
 objcMessageExpr(hasAnyArgument(integerLiteral(equals(12))))
-  matches [i f:12]
+matches [i f:12]
 </pre></td></tr>
 
 
@@ -6884,15 +9225,17 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasArgument1"><pre>Matches the n'th argument of a call expression or a constructor
 call expression.
 
-Example matches y in x(y)
-    (matcher = callExpr(hasArgument(0, declRefExpr())))
+Given
   void x(int) { int y; x(y); }
+The matcher callExpr(hasArgument(0, declRefExpr().bind("arg")))
+matches x(y),
+with declRefExpr() matching y.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('hasDeclaration13')"><a name="hasDeclaration13Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration13"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -6902,17 +9245,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -6929,10 +9280,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   class A { A() : i(42), j(42) {} int i; int j; };
-cxxConstructorDecl(forEachConstructorInitializer(
-  forField(decl().bind("x"))
-))
-  will trigger two matches, binding for 'i' and 'j' respectively.
+
+The matcher cxxConstructorDecl(forEachConstructorInitializer(
+  forField(fieldDecl().bind("x"))))
+matches the constructor of A twice, with
+fieldDecl() matching i and
+j respectively.
 </pre></td></tr>
 
 
@@ -6944,10 +9297,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     Foo() : foo_(1) { }
     int foo_;
   };
-cxxRecordDecl(has(cxxConstructorDecl(
+
+The matcher cxxRecordDecl(has(cxxConstructorDecl(
   hasAnyConstructorInitializer(anything())
 )))
-  record matches Foo, hasAnyConstructorInitializer matches foo_(1)
+matches Foo, hasAnyConstructorInitializer matches foo_(1)
 </pre></td></tr>
 
 
@@ -6959,9 +9313,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     Foo() : foo_(1) { }
     int foo_;
   };
+
+The matcher
 cxxRecordDecl(has(cxxConstructorDecl(hasAnyConstructorInitializer(
     forField(hasName("foo_"))))))
-  matches Foo
+matches Foo
 with forField matching foo_
 </pre></td></tr>
 
@@ -6969,19 +9325,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>></td><td class="name" onclick="toggle('hasTypeLoc2')"><a name="hasTypeLoc2Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc2"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -7002,9 +9365,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     Foo() : foo_(1) { }
     int foo_;
   };
+
+The matcher
 cxxRecordDecl(has(cxxConstructorDecl(hasAnyConstructorInitializer(
     withInitializer(integerLiteral(equals(1)))))))
-  matches Foo
+matches Foo
 with withInitializer matching (1)
 </pre></td></tr>
 
@@ -7019,11 +9384,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     int m;
     int f(X x) { x.m; return m; }
   };
+
+
+The matcher
 memberExpr(hasObjectExpression(hasType(cxxRecordDecl(hasName("X")))))
-  matches `x.m`, but not `m`; however,
-memberExpr(hasObjectExpression(hasType(pointsTo(
-     cxxRecordDecl(hasName("X"))))))
-  matches `m` (aka. `this->m`), but not `x.m`.
+matches x.m, but not m; however,
+The matcher memberExpr(hasObjectExpression(hasType(pointsTo(
+cxxRecordDecl(hasName("X"))))))
+matches m (aka. this->m), but not x.m.
 </pre></td></tr>
 
 
@@ -7033,12 +9401,20 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 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
+
+The matcher callExpr(callee(expr().bind("callee")))
+matches this->x(), x(), y.x(), f()
+with expr() inside of callee
+matching this->x, x,
+y.x, f respectively
 
 Given
+  struct Dummy {};
+  // makes sure there is a callee, otherwise there would be no callee,
+  // just a builtin operator
+  Dummy operator+(Dummy, Dummy);
+  // not defining a '*' operator
+
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
@@ -7048,10 +9424,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   auto multiply(Args... args) {
       return (args * ... * 1);
   }
-cxxFoldExpr(callee(expr()))
-  matches (args * ... * 1)
-with callee(...)
-  matching *
+
+The matcher cxxFoldExpr(callee(expr().bind("op")))
+matches (0 + ... + args)
+with callee(...) matching *,
+but does not match (args * ... * 1).
+A CXXFoldExpr only has an UnresolvedLookupExpr as a callee.
+When there are no define operators that could be used instead of builtin
+ones, then there will be no callee .
 
 Note: Callee cannot take the more general internal::Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>
 because this introduces ambiguous overloads with calls to Callee taking a
@@ -7063,16 +9443,37 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>></td><td class="name" onclick="toggle('hasEitherOperand2')"><a name="hasEitherOperand2Anchor">hasEitherOperand</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasEitherOperand2"><pre>Matches if either the left hand side or the right hand side of a
 binary operator or fold expression matches.
+
+Given
+  struct S {};
+  bool operator ==(const S&, const S&);
+
+  void f(int a, const S&lhs, const S&rhs) {
+      a + 0;
+      lhs == rhs;
+      lhs != rhs;
+  }
+
+  template <typename ...Ts>
+  auto sum(Ts... args) {
+    return (0 + ... + args);
+  }
+
+
+The matcher binaryOperator(hasEitherOperand(integerLiteral()))
+matches a + 0.
+The matcher cxxOperatorCallExpr(hasEitherOperand(declRefExpr(to(
+parmVarDecl(hasName("lhs")))))) matches lhs == rhs and
+lhs != rhs.
+The matcher cxxFoldExpr(hasEitherOperand(integerLiteral()))
+matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>></td><td class="name" onclick="toggle('hasFoldInit0')"><a name="hasFoldInit0Anchor">hasFoldInit</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMacher</td></tr>
 <tr><td colspan="4" class="doc" id="hasFoldInit0"><pre>Matches the operand that does not contain the parameter pack.
 
-Example matches `(0 + ... + args)` and `(args * ... * 1)`
-    (matcher = cxxFoldExpr(hasFoldInit(expr())))
-  with hasFoldInit(...)
-    matching `0` and `1` respectively
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
@@ -7082,14 +9483,27 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   auto multiply(Args... args) {
       return (args * ... * 1);
   }
+
+
+The matcher cxxFoldExpr(hasFoldInit(expr().bind("init")))
+matches (0 + ... + args) and (args * ... * 1)
+with hasFoldInit(expr().bind("init")) matching
+0 and 1.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>></td><td class="name" onclick="toggle('hasLHS4')"><a name="hasLHS4Anchor">hasLHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasLHS4"><pre>Matches the left hand side of binary operator expressions.
 
-Example matches a (matcher = binaryOperator(hasLHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasLHS(expr().bind("lhs")))
+matches a || b,
+with expr()
+matching a.
 </pre></td></tr>
 
 
@@ -7097,22 +9511,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperands2"><pre>Matches if both matchers match with opposite sides of the binary operator
 or fold expression.
 
-Example matcher = binaryOperator(hasOperands(integerLiteral(equals(1),
-                                             integerLiteral(equals(2)))
-  1 + 2 // Match
-  2 + 1 // Match
-  1 + 1 // No match
-  2 + 2 // No match
+Given
+void foo() {
+  1 + 2; // Match
+  2 + 1; // Match
+  1 + 1; // No match
+  2 + 2; // No match
+}
+The matcher binaryOperator(hasOperands(integerLiteral(equals(1)),
+                                            integerLiteral(equals(2))))
+matches 1 + 2 and 2 + 1,
+but does not match 1 + 1
+or 2 + 2.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>></td><td class="name" onclick="toggle('hasPattern0')"><a name="hasPattern0Anchor">hasPattern</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMacher</td></tr>
 <tr><td colspan="4" class="doc" id="hasPattern0"><pre>Matches the operand that contains the parameter pack.
 
-Example matches `(0 + ... + args)`
-    (matcher = cxxFoldExpr(hasPattern(expr())))
-  with hasPattern(...)
-    matching `args`
+Given
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
@@ -7122,14 +9539,27 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   auto multiply(Args... args) {
       return (args * ... * 1);
   }
+
+
+The matcher cxxFoldExpr(hasPattern(expr().bind("pattern")))
+matches (0 + ... + args) and (args * ... * 1),
+with hasPattern(expr().bind("pattern")) matching
+args two times.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFoldExpr.html">CXXFoldExpr</a>></td><td class="name" onclick="toggle('hasRHS4')"><a name="hasRHS4Anchor">hasRHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasRHS4"><pre>Matches the right hand side of binary operator expressions.
 
-Example matches b (matcher = binaryOperator(hasRHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasRHS(expr().bind("rhs")))
+matches a || b,
+with expr()
+matching b.
 </pre></td></tr>
 
 
@@ -7140,27 +9570,32 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 other declarations of the same function or coroutine.
 
 Given
+void foo() {
   for (;;) {}
-forStmt(hasBody(compoundStmt()))
-  matches 'for (;;) {}'
+}
+The matcher forStmt(hasBody(compoundStmt().bind("body")))
+matches for (;;) {}
 with compoundStmt()
-  matching '{}'
+  matching {}
 
 Given
   void f();
   void f() {}
-functionDecl(hasBody(compoundStmt()))
-  matches 'void f() {}'
+The matcher functionDecl(hasBody(compoundStmt().bind("compound")))
+f
 with compoundStmt()
-  matching '{}'
-  but does not match 'void f();'
+matching {}
+but does not match void f();
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasInitStatement2')"><a name="hasInitStatement2Anchor">hasInitStatement</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasInitStatement2"><pre>Matches selection statements with initializer.
 
-Given:
+Given
+ struct vec { int* begin(); int* end(); };
+ int foobar();
+ vec& get_range();
  void foo() {
    if (int i = foobar(); i > 0) {}
    switch (int i = foobar(); i) {}
@@ -7171,51 +9606,71 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
    switch (foobar()) {}
    for (auto& x : get_range()) {}
  }
-ifStmt(hasInitStatement(anything()))
-  matches the if statement in foo but not in bar.
-switchStmt(hasInitStatement(anything()))
-  matches the switch statement in foo but not in bar.
-cxxForRangeStmt(hasInitStatement(anything()))
-  matches the range for statement in foo but not in bar.
+
+The matcher ifStmt(hasInitStatement(anything()))
+  matches the if statement if (int i = foobar(); i > 0) {}
+  in foo but not if (foobar() > 0) {} in bar.
+The matcher switchStmt(hasInitStatement(anything()))
+  matches the switch statement switch (int i = foobar(); i) {}
+  in foo but not switch (foobar()) {} in bar.
+The matcher cxxForRangeStmt(hasInitStatement(anything()))
+  matches the range for statement
+  for (auto& a = get_range(); auto& x : a) {} in foo
+  but not for (auto& x : get_range()) {} in bar.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasLoopVariable0')"><a name="hasLoopVariable0Anchor">hasLoopVariable</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasLoopVariable0"><pre>Matches the initialization statement of a for loop.
 
-Example:
-    forStmt(hasLoopVariable(anything()))
-matches 'int x' in
+Given
+  void foo() {
+    int a[42] = {};
     for (int x : a) { }
+  }
+
+The matcher cxxForRangeStmt(hasLoopVariable(anything()))
+matches for (int x : a) { }
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasRangeInit0')"><a name="hasRangeInit0Anchor">hasRangeInit</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasRangeInit0"><pre>Matches the range initialization statement of a for loop.
 
-Example:
-    forStmt(hasRangeInit(anything()))
-matches 'a' in
+Given
+  void foo() {
+    int a[42] = {};
     for (int x : a) { }
+  }
+
+The matcher cxxForRangeStmt(hasRangeInit(anything()))
+matches for (int x : a) { }
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>></td><td class="name" onclick="toggle('hasTypeLoc3')"><a name="hasTypeLoc3Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc3"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -7235,13 +9690,16 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   class Y { public: void m(); };
   Y g();
-  class X : public Y { void g(); };
+  class X : public Y { public: void g(); };
   void z(Y y, X x) { y.m(); x.m(); x.g(); (g()).m(); }
-cxxMemberCallExpr(onImplicitObjectArgument(hasType(
+
+The matcher cxxMemberCallExpr(onImplicitObjectArgument(hasType(
     cxxRecordDecl(hasName("Y")))))
-  matches `y.m()`, `x.m()` and (g()).m(), but not `x.g()`.
-cxxMemberCallExpr(on(callExpr()))
-  does not match `(g()).m()`, because the parens are not ignored.
+matches y.m(), x.m() and (g()).m()
+but does not match x.g().
+The matcher cxxMemberCallExpr(on(callExpr()))
+matches (g()).m(), because the parens are ignored.
+FIXME: should they be ignored? (ignored bc of `on`)
 
 FIXME: Overload to allow directly matching types?
 </pre></td></tr>
@@ -7256,12 +9714,15 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   Y g();
   class X : public Y {};
   void z(Y y, X x) { y.m(); (g()).m(); x.m(); }
+
+The matcher
 cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("Y")))))
-  matches `y.m()` and `(g()).m()`.
+  matches y.m() and (g()).m().
+The matcher
 cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("X")))))
-  matches `x.m()`.
-cxxMemberCallExpr(on(callExpr()))
-  matches `(g()).m()`.
+  matches x.m().
+The matcher cxxMemberCallExpr(on(callExpr()))
+  matches (g()).m().
 
 FIXME: Overload to allow directly matching types?
 </pre></td></tr>
@@ -7269,24 +9730,35 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('thisPointerType1')"><a name="thisPointerType1Anchor">thisPointerType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="thisPointerType1"><pre>Overloaded to match the type's declaration.
+
+Given
+  class Y { public: void m(); };
+  class X : public Y { public: void g(); };
+  void z() { Y y; y.m(); Y *p; p->m(); X x; x.m(); x.g(); }
+
+The matcher cxxMemberCallExpr(thisPointerType(
+    cxxRecordDecl(hasName("Y"))))
+  matches y.m(), p->m() and x.m().
+The matcher cxxMemberCallExpr(thisPointerType(
+    cxxRecordDecl(hasName("X"))))
+  matches x.g().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('thisPointerType0')"><a name="thisPointerType0Anchor">thisPointerType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="thisPointerType0"><pre>Matches if the type of the expression's implicit object argument either
-matches the InnerMatcher, or is a pointer to a type that matches the
+  matches the InnerMatcher, or is a pointer to a type that matches the
 InnerMatcher.
 
 Given
-  class Y { public: void m(); };
-  class X : public Y { void g(); };
-  void z() { Y y; y.m(); Y *p; p->m(); X x; x.m(); x.g(); }
-cxxMemberCallExpr(thisPointerType(hasDeclaration(
-    cxxRecordDecl(hasName("Y")))))
-  matches `y.m()`, `p->m()` and `x.m()`.
-cxxMemberCallExpr(thisPointerType(hasDeclaration(
-    cxxRecordDecl(hasName("X")))))
-  matches `x.g()`.
+  class Y { public: void m() const; };
+  class X : public Y { public: void g(); };
+  void z() { const Y y; y.m(); const Y *p; p->m(); X x; x.m(); x.g(); }
+
+The matcher
+cxxMemberCallExpr(thisPointerType(isConstQualified()))
+matches y.m(), x.m() and p->m(),
+but not x.g().
 </pre></td></tr>
 
 
@@ -7298,19 +9770,27 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   class A { virtual void f(); };
   class B : public A { void f(); };
   class C : public B { void f(); };
-cxxMethodDecl(ofClass(hasName("C")),
-              forEachOverridden(cxxMethodDecl().bind("b"))).bind("d")
-  matches once, with "b" binding "A::f" and "d" binding "C::f" (Note
-  that B::f is not overridden by C::f).
+
+The matcher cxxMethodDecl(ofClass(hasName("C")),
+              forEachOverridden(cxxMethodDecl().bind("b")))
+matches void f() of C ,
+with cxxMethodDecl() matching
+virtual void f() of A ,
+but the matcher does not match void f() of B because
+it is not overridden by C::f.
 
 The check can produce multiple matches in case of multiple inheritance, e.g.
   class A1 { virtual void f(); };
   class A2 { virtual void f(); };
   class C : public A1, public A2 { void f(); };
-cxxMethodDecl(ofClass(hasName("C")),
-              forEachOverridden(cxxMethodDecl().bind("b"))).bind("d")
-  matches twice, once with "b" binding "A1::f" and "d" binding "C::f", and
-  once with "b" binding "A2::f" and "d" binding "C::f".
+
+The matcher cxxMethodDecl(ofClass(hasName("C")),
+              forEachOverridden(cxxMethodDecl().bind("b")))
+matches void f() of C with the inner
+cxxMethodDecl() matching virtual void f()
+inside of A1 , and void f() of C with the inner
+cxxMethodDecl() matching virtual void f()
+inside of A2.
 </pre></td></tr>
 
 
@@ -7322,40 +9802,52 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 FIXME: What other kind of declarations would we need to generalize
 this to?
 
-Example matches A() in the last line
-    (matcher = cxxConstructExpr(hasDeclaration(cxxMethodDecl(
-        ofClass(hasName("A"))))))
+Given
   class A {
    public:
     A();
+    void foo();
   };
-  A a = A();
+
+The matcher cxxMethodDecl(ofClass(hasName("A")))
+matches A() and void foo().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>></td><td class="name" onclick="toggle('hasAnyPlacementArg0')"><a name="hasAnyPlacementArg0Anchor">hasAnyPlacementArg</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasAnyPlacementArg0"><pre>Matches any placement new expression arguments.
 
-Given:
+Given
+  void* operator new(decltype(sizeof(void*)), void*);
+  struct MyClass { int x; };
+  unsigned char Storage[sizeof(MyClass) * 10];
   MyClass *p1 = new (Storage) MyClass();
-cxxNewExpr(hasAnyPlacementArg(anything()))
-  matches the expression 'new (Storage, 16) MyClass()'.
+
+
+The matcher cxxNewExpr(hasAnyPlacementArg(anything()))
+matches new (Storage) MyClass().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>></td><td class="name" onclick="toggle('hasArraySize0')"><a name="hasArraySize0Anchor">hasArraySize</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasArraySize0"><pre>Matches array new expressions with a given array size.
 
-Given:
+Given
+  void* operator new(decltype(sizeof(void*)));
+  struct MyClass { int x; };
   MyClass *p1 = new MyClass[10];
-cxxNewExpr(hasArraySize(integerLiteral(equals(10))))
-  matches the expression 'new MyClass[10]'.
+
+
+The matcher
+cxxNewExpr(hasArraySize(
+            ignoringImplicit(integerLiteral(equals(10)))))
+matches new MyClass[10].
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>></td><td class="name" onclick="toggle('hasDeclaration12')"><a name="hasDeclaration12Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration12"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -7365,17 +9857,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -7390,29 +9890,42 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>></td><td class="name" onclick="toggle('hasPlacementArg0')"><a name="hasPlacementArg0Anchor">hasPlacementArg</a></td><td>unsigned Index, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasPlacementArg0"><pre>Matches placement new expression arguments.
 
-Given:
-  MyClass *p1 = new (Storage, 16) MyClass();
-cxxNewExpr(hasPlacementArg(1, integerLiteral(equals(16))))
-  matches the expression 'new (Storage, 16) MyClass()'.
+Given
+  void *operator new(decltype(sizeof(void*)), int, void*);
+  struct MyClass { int x; };
+  unsigned char Storage[sizeof(MyClass) * 10];
+  MyClass *p1 = new (16, Storage) MyClass();
+
+
+The matcher cxxNewExpr(hasPlacementArg(0,
+                      integerLiteral(equals(16))))
+matches new (16, Storage) MyClass().
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>></td><td class="name" onclick="toggle('hasTypeLoc4')"><a name="hasTypeLoc4Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc4"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -7428,14 +9941,45 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>></td><td class="name" onclick="toggle('hasEitherOperand1')"><a name="hasEitherOperand1Anchor">hasEitherOperand</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasEitherOperand1"><pre>Matches if either the left hand side or the right hand side of a
 binary operator or fold expression matches.
+
+Given
+  struct S {};
+  bool operator ==(const S&, const S&);
+
+  void f(int a, const S&lhs, const S&rhs) {
+      a + 0;
+      lhs == rhs;
+      lhs != rhs;
+  }
+
+  template <typename ...Ts>
+  auto sum(Ts... args) {
+    return (0 + ... + args);
+  }
+
+
+The matcher binaryOperator(hasEitherOperand(integerLiteral()))
+matches a + 0.
+The matcher cxxOperatorCallExpr(hasEitherOperand(declRefExpr(to(
+parmVarDecl(hasName("lhs")))))) matches lhs == rhs and
+lhs != rhs.
+The matcher cxxFoldExpr(hasEitherOperand(integerLiteral()))
+matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>></td><td class="name" onclick="toggle('hasLHS1')"><a name="hasLHS1Anchor">hasLHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasLHS1"><pre>Matches the left hand side of binary operator expressions.
 
-Example matches a (matcher = binaryOperator(hasLHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasLHS(expr().bind("lhs")))
+matches a || b,
+with expr()
+matching a.
 </pre></td></tr>
 
 
@@ -7443,44 +9987,64 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperands1"><pre>Matches if both matchers match with opposite sides of the binary operator
 or fold expression.
 
-Example matcher = binaryOperator(hasOperands(integerLiteral(equals(1),
-                                             integerLiteral(equals(2)))
-  1 + 2 // Match
-  2 + 1 // Match
-  1 + 1 // No match
-  2 + 2 // No match
+Given
+void foo() {
+  1 + 2; // Match
+  2 + 1; // Match
+  1 + 1; // No match
+  2 + 2; // No match
+}
+The matcher binaryOperator(hasOperands(integerLiteral(equals(1)),
+                                            integerLiteral(equals(2))))
+matches 1 + 2 and 2 + 1,
+but does not match 1 + 1
+or 2 + 2.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>></td><td class="name" onclick="toggle('hasRHS1')"><a name="hasRHS1Anchor">hasRHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasRHS1"><pre>Matches the right hand side of binary operator expressions.
 
-Example matches b (matcher = binaryOperator(hasRHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasRHS(expr().bind("rhs")))
+matches a || b,
+with expr()
+matching b.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>></td><td class="name" onclick="toggle('hasUnaryOperand1')"><a name="hasUnaryOperand1Anchor">hasUnaryOperand</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasUnaryOperand1"><pre>Matches if the operand of a unary operator matches.
 
-Example matches true (matcher = hasUnaryOperand(
-                                  cxxBoolLiteral(equals(true))))
-  !true
+void foo() {
+  !true;
+}
+
+The matcher
+unaryOperator(hasUnaryOperand(cxxBoolLiteral(equals(true))))
+matches !true.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('hasAnyBase0')"><a name="hasAnyBase0Anchor">hasAnyBase</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>> BaseSpecMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasAnyBase0"><pre>Matches C++ classes that have a direct or indirect base matching BaseSpecMatcher.
 
-Example:
-matcher hasAnyBase(hasType(cxxRecordDecl(hasName("SpecialBase"))))
-  class Foo;
+Given
+  class Foo {};
   class Bar : Foo {};
   class Baz : Bar {};
-  class SpecialBase;
+  class SpecialBase {};
   class Proxy : SpecialBase {};  // matches Proxy
   class IndirectlyDerived : Proxy {};  //matches IndirectlyDerived
 
+
+The matcher
+cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("SpecialBase")))))
+matches Proxy and IndirectlyDerived
 FIXME: Refactor this and isDerivedFrom to reuse implementation.
 </pre></td></tr>
 
@@ -7488,26 +10052,31 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('hasDirectBase0')"><a name="hasDirectBase0Anchor">hasDirectBase</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>> BaseSpecMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDirectBase0"><pre>Matches C++ classes that have a direct base matching BaseSpecMatcher.
 
-Example:
-matcher hasDirectBase(hasType(cxxRecordDecl(hasName("SpecialBase"))))
-  class Foo;
+Given
+  class Foo {};
   class Bar : Foo {};
   class Baz : Bar {};
-  class SpecialBase;
+  class SpecialBase {};
   class Proxy : SpecialBase {};  // matches Proxy
   class IndirectlyDerived : Proxy {};  // doesn't match
+
+The matcher
+cxxRecordDecl(hasDirectBase(hasType(cxxRecordDecl(hasName("SpecialBase")))))
+matches Proxy
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('hasMethod0')"><a name="hasMethod0Anchor">hasMethod</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasMethod0"><pre>Matches the first method of a class or struct that satisfies InnerMatcher.
 
-Given:
+Given
   class A { void func(); };
   class B { void member(); };
 
-cxxRecordDecl(hasMethod(hasName("func"))) matches the declaration of
-A but not B.
+
+The matcher cxxRecordDecl(hasMethod(hasName("func")))
+matches the declaration of class A { void func(); }
+but does not match class B { void member(); }
 </pre></td></tr>
 
 
@@ -7519,22 +10088,29 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Note that a class is not considered to be derived from itself.
 
 Example matches Y, Z, C (Base == hasName("X"))
-  class X;
+  class X {};
   class Y : public X {};  // directly derived
   class Z : public Y {};  // indirectly derived
   typedef X A;
   typedef A B;
   class C : public B {};  // derived from a typedef of X
 
-In the following example, Bar matches isDerivedFrom(hasName("X")):
-  class Foo;
-  typedef Foo X;
-  class Bar : public Foo {};  // derived from a type that X is a typedef of
+  class Foo {};
+  typedef Foo Alias;
+  class Bar : public Alias {};
+  // derived from a type that Alias is a typedef of Foo
+
+
+The matcher cxxRecordDecl(isDerivedFrom(hasName("X")))
+matches Y, Z and C.
+The matcher cxxRecordDecl(isDerivedFrom(hasName("Foo")))
+matches Bar.
 
 In the following example, Bar matches isDerivedFrom(hasName("NSObject"))
   @interface NSObject @end
   @interface Bar : NSObject @end
 
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCInterfaceDecl.html">ObjCInterfaceDecl</a>>
 </pre></td></tr>
 
@@ -7545,38 +10121,90 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Note that a class is not considered to be derived from itself.
 
-Example matches Y, C (Base == hasName("X"))
-  class X;
+Given
+  class X {};
   class Y : public X {};  // directly derived
   class Z : public Y {};  // indirectly derived
   typedef X A;
   typedef A B;
   class C : public B {};  // derived from a typedef of X
 
+The matcher
+cxxRecordDecl(isDirectlyDerivedFrom(namedDecl(hasName("X"))))
+matches Y and C (Base == hasName("X")
+
 In the following example, Bar matches isDerivedFrom(hasName("X")):
-  class Foo;
+  class Foo {};
   typedef Foo X;
   class Bar : public Foo {};  // derived from a type that X is a typedef of
+
+The matcher cxxRecordDecl(isDerivedFrom(hasName("X")))
+matches Bar
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('isSameOrDerivedFrom0')"><a name="isSameOrDerivedFrom0Anchor">isSameOrDerivedFrom</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>> Base</td></tr>
 <tr><td colspan="4" class="doc" id="isSameOrDerivedFrom0"><pre>Similar to isDerivedFrom(), but also matches classes that directly
 match Base.
+
+Given
+  class X {};
+  class Y : public X {};  // directly derived
+  class Z : public Y {};  // indirectly derived
+  typedef X A;
+  typedef A B;
+  class C : public B {};  // derived from a typedef of X
+
+The matcher
+cxxRecordDecl(isSameOrDerivedFrom(cxxRecordDecl(hasName("X"))),
+isDefinition())
+matches class X {}, class Y : public X {},
+class Z : public Y {} and class C : public B {}.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRewrittenBinaryOperator.html">CXXRewrittenBinaryOperator</a>></td><td class="name" onclick="toggle('hasEitherOperand3')"><a name="hasEitherOperand3Anchor">hasEitherOperand</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasEitherOperand3"><pre>Matches if either the left hand side or the right hand side of a
 binary operator or fold expression matches.
+
+Given
+  struct S {};
+  bool operator ==(const S&, const S&);
+
+  void f(int a, const S&lhs, const S&rhs) {
+      a + 0;
+      lhs == rhs;
+      lhs != rhs;
+  }
+
+  template <typename ...Ts>
+  auto sum(Ts... args) {
+    return (0 + ... + args);
+  }
+
+
+The matcher binaryOperator(hasEitherOperand(integerLiteral()))
+matches a + 0.
+The matcher cxxOperatorCallExpr(hasEitherOperand(declRefExpr(to(
+parmVarDecl(hasName("lhs")))))) matches lhs == rhs and
+lhs != rhs.
+The matcher cxxFoldExpr(hasEitherOperand(integerLiteral()))
+matches (0 + ... + args).
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRewrittenBinaryOperator.html">CXXRewrittenBinaryOperator</a>></td><td class="name" onclick="toggle('hasLHS2')"><a name="hasLHS2Anchor">hasLHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasLHS2"><pre>Matches the left hand side of binary operator expressions.
 
-Example matches a (matcher = binaryOperator(hasLHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasLHS(expr().bind("lhs")))
+matches a || b,
+with expr()
+matching a.
 </pre></td></tr>
 
 
@@ -7584,39 +10212,59 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasOperands3"><pre>Matches if both matchers match with opposite sides of the binary operator
 or fold expression.
 
-Example matcher = binaryOperator(hasOperands(integerLiteral(equals(1),
-                                             integerLiteral(equals(2)))
-  1 + 2 // Match
-  2 + 1 // Match
-  1 + 1 // No match
-  2 + 2 // No match
+Given
+void foo() {
+  1 + 2; // Match
+  2 + 1; // Match
+  1 + 1; // No match
+  2 + 2; // No match
+}
+The matcher binaryOperator(hasOperands(integerLiteral(equals(1)),
+                                            integerLiteral(equals(2))))
+matches 1 + 2 and 2 + 1,
+but does not match 1 + 1
+or 2 + 2.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRewrittenBinaryOperator.html">CXXRewrittenBinaryOperator</a>></td><td class="name" onclick="toggle('hasRHS2')"><a name="hasRHS2Anchor">hasRHS</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasRHS2"><pre>Matches the right hand side of binary operator expressions.
 
-Example matches b (matcher = binaryOperator(hasRHS()))
-  a || b
+Given
+void foo(bool a, bool b) {
+  a || b;
+}
+
+The matcher binaryOperator(hasRHS(expr().bind("rhs")))
+matches a || b,
+with expr()
+matching b.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXTemporaryObjectExpr.html">CXXTemporaryObjectExpr</a>></td><td class="name" onclick="toggle('hasTypeLoc5')"><a name="hasTypeLoc5Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc5"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -7634,17 +10282,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 expression, or an ObjC-message-send expression.
 
 Given
-  void x(int, int, int) { int y; x(1, y, 42); }
-callExpr(hasAnyArgument(declRefExpr()))
-  matches x(1, y, 42)
-with hasAnyArgument(...)
+  void x(int, int, int) { int y = 42; x(1, y, 42); }
+The matcher
+callExpr(hasAnyArgument(ignoringImplicit(declRefExpr()))) matches
+x(1, y, 42) with hasAnyArgument(...)
   matching y
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
   void foo(I *i) { [i f:12]; }
+
+The matcher
 objcMessageExpr(hasAnyArgument(integerLiteral(equals(12))))
-  matches [i f:12]
+matches [i f:12]
 </pre></td></tr>
 
 
@@ -7652,28 +10302,37 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasArgument2"><pre>Matches the n'th argument of a call expression or a constructor
 call expression.
 
-Example matches y in x(y)
-    (matcher = callExpr(hasArgument(0, declRefExpr())))
+Given
   void x(int) { int y; x(y); }
+The matcher callExpr(hasArgument(0, declRefExpr().bind("arg")))
+matches x(y),
+with declRefExpr() matching y.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXUnresolvedConstructExpr.html">CXXUnresolvedConstructExpr</a>></td><td class="name" onclick="toggle('hasTypeLoc6')"><a name="hasTypeLoc6Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc6"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -7691,19 +10350,23 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 given matcher; or 2) if the Obj-C message expression's callee's method
 declaration matches the given matcher.
 
-Example matches y.x() (matcher = callExpr(callee(
-                                   cxxMethodDecl(hasName("x")))))
+Example 1
   class Y { public: void x(); };
   void z() { Y y; y.x(); }
 
-Example 2. Matches [I foo] with
-objcMessageExpr(callee(objcMethodDecl(hasName("foo"))))
+The matcher callExpr(callee(cxxMethodDecl(hasName("x"))))
+matches y.x()
 
+Example 2
   @interface I: NSObject
   +(void)foo;
   @end
   ...
   [I foo]
+
+The matcher
+objcMessageExpr(callee(objcMethodDecl(hasName("foo"))))
+matches [I foo]
 </pre></td></tr>
 
 
@@ -7713,12 +10376,20 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 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
+
+The matcher callExpr(callee(expr().bind("callee")))
+matches this->x(), x(), y.x(), f()
+with expr() inside of callee
+matching this->x, x,
+y.x, f respectively
 
 Given
+  struct Dummy {};
+  // makes sure there is a callee, otherwise there would be no callee,
+  // just a builtin operator
+  Dummy operator+(Dummy, Dummy);
+  // not defining a '*' operator
+
   template <typename... Args>
   auto sum(Args... args) {
       return (0 + ... + args);
@@ -7728,10 +10399,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   auto multiply(Args... args) {
       return (args * ... * 1);
   }
-cxxFoldExpr(callee(expr()))
-  matches (args * ... * 1)
-with callee(...)
-  matching *
+
+The matcher cxxFoldExpr(callee(expr().bind("op")))
+matches (0 + ... + args)
+with callee(...) matching *,
+but does not match (args * ... * 1).
+A CXXFoldExpr only has an UnresolvedLookupExpr as a callee.
+When there are no define operators that could be used instead of builtin
+ones, then there will be no callee .
 
 Note: Callee cannot take the more general internal::Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>
 because this introduces ambiguous overloads with calls to Callee taking a
@@ -7746,8 +10421,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   void f(int i);
   int y;
-  f(y);
-callExpr(
+  void foo() {
+    f(y);
+  }
+The matcher callExpr(
   forEachArgumentWithParam(
     declRefExpr(to(varDecl(hasName("y")))),
     parmVarDecl(hasType(isInteger()))
@@ -7770,14 +10447,15 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   void f(int i);
-  int y;
-  f(y);
-  void (*f_ptr)(int) = f;
-  f_ptr(y);
-callExpr(
+  void foo(int y) {
+    f(y);
+    void (*f_ptr)(int) = f;
+    f_ptr(y);
+  }
+The matcher callExpr(
   forEachArgumentWithParamType(
     declRefExpr(to(varDecl(hasName("y")))),
-    qualType(isInteger()).bind("type)
+    qualType(isInteger()).bind("type")
 ))
   matches f(y) and f_ptr(y)
 with declRefExpr(...)
@@ -7792,17 +10470,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 expression, or an ObjC-message-send expression.
 
 Given
-  void x(int, int, int) { int y; x(1, y, 42); }
-callExpr(hasAnyArgument(declRefExpr()))
-  matches x(1, y, 42)
-with hasAnyArgument(...)
+  void x(int, int, int) { int y = 42; x(1, y, 42); }
+The matcher
+callExpr(hasAnyArgument(ignoringImplicit(declRefExpr()))) matches
+x(1, y, 42) with hasAnyArgument(...)
   matching y
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
   void foo(I *i) { [i f:12]; }
+
+The matcher
 objcMessageExpr(hasAnyArgument(integerLiteral(equals(12))))
-  matches [i f:12]
+matches [i f:12]
 </pre></td></tr>
 
 
@@ -7810,15 +10490,17 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasArgument0"><pre>Matches the n'th argument of a call expression or a constructor
 call expression.
 
-Example matches y in x(y)
-    (matcher = callExpr(hasArgument(0, declRefExpr())))
+Given
   void x(int) { int y; x(y); }
+The matcher callExpr(hasArgument(0, declRefExpr().bind("arg")))
+matches x(y),
+with declRefExpr() matching y.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('hasDeclaration14')"><a name="hasDeclaration14Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration14"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -7828,17 +10510,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -7855,9 +10545,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 extension, matches the constant given in the statement.
 
 Given
-  switch (1) { case 1: case 1+1: case 3 ... 4: ; }
-caseStmt(hasCaseConstant(integerLiteral()))
-  matches "case 1:"
+  void foo() {
+    switch (1) { case 1: break; case 1+1: break; case 3 ... 4: break; }
+  }
+The matcher
+caseStmt(hasCaseConstant(constantExpr(has(integerLiteral()))))
+matches case 1: break.
 </pre></td></tr>
 
 
@@ -7865,14 +10558,23 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasSourceExpression0"><pre>Matches if the cast's source expression
 or opaque value's source expression matches the given matcher.
 
-Example 1: matches "a string"
-(matcher = castExpr(hasSourceExpression(cxxConstructExpr())))
-class URL { URL(string); };
-URL url = "a string";
+Given
+ struct URL { URL(const char*); };
+ URL url = "a string";
+
+The matcher castExpr(hasSourceExpression(cxxConstructExpr()))
+matches "a string".
+
+Given
+void foo(bool b) {
+  int a = b ?: 1;
+}
 
-Example 2: matches 'b' (matcher =
-opaqueValueExpr(hasSourceExpression(implicitCastExpr(declRefExpr())))
-int a = b ?: 1;
+The matcher
+opaqueValueExpr(hasSourceExpression(
+              implicitCastExpr(has(
+                implicitCastExpr(has(declRefExpr()))))))
+matches b twice, for the conditiona and the true expression.
 </pre></td></tr>
 
 
@@ -7892,13 +10594,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template <typename T, typename U>
   void f(T&& t, U&& u) {}
 
-  bool B = false;
-  f(R, B);
-templateSpecializationType(forEachTemplateArgument(isExpr(expr())))
-  matches twice, with expr() matching 'R * 2' and 'R * 4'
-functionDecl(forEachTemplateArgument(refersToType(builtinType())))
-  matches the specialization f<unsigned, bool> twice, for 'unsigned'
-  and 'bool'
+  void foo() {
+    bool B = false;
+    f(R, B);
+  }
+
+The matcher
+templateSpecializationType(forEachTemplateArgument(isExpr(expr().bind("t_arg"))))
+matches Matrix<int, R * 2, R * 4> twice, with
+expr() matching R * 2 and
+R * 4.
+The matcher
+functionDecl(forEachTemplateArgument(refersToType(qualType().bind("type"))))
+matches the specialization of f twice,
+with qualType() matching
+unsigned and
+bool.
 </pre></td></tr>
 
 
@@ -7911,9 +10622,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   template<typename T> class A {};
   A<int> a;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
-  hasTypeLoc(loc(asString("int")))))))
-  matches `A<int> a`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
+hasTypeLoc(loc(asString("int"))))))))) matches A<int> a.
 </pre></td></tr>
 
 
@@ -7927,15 +10640,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<> class A<double> {};
   A<int> a;
 
-  template<typename T> f() {};
+  template<typename T> void f() {};
   void func() { f<int>(); };
 
-classTemplateSpecializationDecl(hasAnyTemplateArgument(
-    refersToType(asString("int"))))
-  matches the specialization A<int>
 
-functionDecl(hasAnyTemplateArgument(refersToType(asString("int"))))
-  matches the specialization f<int>
+The matcher classTemplateSpecializationDecl(
+                        hasAnyTemplateArgument(
+                          refersToType(asString("int"))))
+matches class A<int>.
+
+The matcher
+functionDecl(hasAnyTemplateArgument(
+              refersToType(asString("int"))))
+matches the instantiation of f.
 </pre></td></tr>
 
 
@@ -7943,11 +10660,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasSpecializedTemplate0"><pre>Matches the specialized template of a specialization declaration.
 
 Given
-  template<typename T> class A {}; #1
-  template<> class A<int> {}; #2
-classTemplateSpecializationDecl(hasSpecializedTemplate(classTemplateDecl()))
-  matches '#2' with classTemplateDecl() matching the class template
-  declaration of 'A' at #1.
+  template<typename T> class A {}; // #1
+  template<> class A<int> {}; // #2
+
+The matcher
+classTemplateSpecializationDecl(hasSpecializedTemplate(classTemplateDecl().bind("ctd")))
+matches template<> class A<int> {},
+with classTemplateDecl() matching the class template
+declaration template <typename T> class A {}.
 </pre></td></tr>
 
 
@@ -7960,9 +10680,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<typename T, typename U> class A {};
   A<double, int> b;
   A<int, double> c;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
-  hasTypeLoc(loc(asString("double")))))))
-  matches `A<double, int> b`, but not `A<int, double> c`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
+hasTypeLoc(loc(asString("double")))))))))
+matches A<double, int> b, but not double> c}.
 </pre></td></tr>
 
 
@@ -7973,17 +10696,20 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   template<typename T, typename U> class A {};
-  A<bool, int> b;
-  A<int, bool> c;
+  A<double, int> b;
+  A<int, double> c;
 
   template<typename T> void f() {}
   void func() { f<int>(); };
+
+The matcher
 classTemplateSpecializationDecl(hasTemplateArgument(
     1, refersToType(asString("int"))))
-  matches the specialization A<bool, int>
+matches the specialization class A<double, int>.
 
-functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
-  matches the specialization f<int>
+The matcher functionDecl(hasTemplateArgument(0,
+                        refersToType(asString("int"))))
+matches the specialization of f.
 </pre></td></tr>
 
 
@@ -7995,8 +10721,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   struct A {};
   A a[7];
   int b[7];
-arrayType(hasElementType(builtinType()))
-  matches "int b[7]"
+
+
+The matcher arrayType(hasElementType(builtinType()))
+int[7]
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ArrayType.html">ArrayType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ComplexType.html">ComplexType</a>>
 </pre></td></tr>
@@ -8005,19 +10733,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CompoundLiteralExpr.html">CompoundLiteralExpr</a>></td><td class="name" onclick="toggle('hasTypeLoc7')"><a name="hasTypeLoc7Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc7"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -8035,11 +10770,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 a given matcher. Also matches StmtExprs that have CompoundStmt as children.
 
 Given
-  { {}; 1+2; }
-hasAnySubstatement(compoundStmt())
-  matches '{ {}; 1+2; }'
+void foo() { { {}; 1+2; } }
+The matcher
+compoundStmt(hasAnySubstatement(compoundStmt().bind("compound")))
+{ {}; 1+2; } and { { {}; 1+2; } }
 with compoundStmt()
-  matching '{}'
+matching {} and { {}; 1+2; }.
 </pre></td></tr>
 
 
@@ -8050,25 +10786,35 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 other declarations of the same function or coroutine.
 
 Given
+void foo() {
   for (;;) {}
-forStmt(hasBody(compoundStmt()))
-  matches 'for (;;) {}'
+}
+The matcher forStmt(hasBody(compoundStmt().bind("body")))
+matches for (;;) {}
 with compoundStmt()
-  matching '{}'
+  matching {}
 
 Given
   void f();
   void f() {}
-functionDecl(hasBody(compoundStmt()))
-  matches 'void f() {}'
+The matcher functionDecl(hasBody(compoundStmt().bind("compound")))
+f
 with compoundStmt()
-  matching '{}'
-  but does not match 'void f();'
+matching {}
+but does not match void f();
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DecayedType.html">DecayedType</a>></td><td class="name" onclick="toggle('hasDecayedType0')"><a name="hasDecayedType0Anchor">hasDecayedType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerType</td></tr>
 <tr><td colspan="4" class="doc" id="hasDecayedType0"><pre>Matches the decayed type, whoes decayed type matches InnerMatcher
+
+Given
+  void f(int i[]) {
+    i[1] = 0;
+  }
+
+The matcher parmVarDecl(hasType(decayedType()))
+matches int i[].
 </pre></td></tr>
 
 
@@ -8081,15 +10827,17 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   template<typename T> class A {};
   A<int> a;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
-  hasTypeLoc(loc(asString("int")))))))
-  matches `A<int> a`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
+hasTypeLoc(loc(asString("int"))))))))) matches A<int> a.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>></td><td class="name" onclick="toggle('hasDeclaration11')"><a name="hasDeclaration11Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration11"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -8099,17 +10847,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -8130,9 +10886,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<typename T, typename U> class A {};
   A<double, int> b;
   A<int, double> c;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
-  hasTypeLoc(loc(asString("double")))))))
-  matches `A<double, int> b`, but not `A<int, double> c`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
+hasTypeLoc(loc(asString("double")))))))))
+matches A<double, int> b, but not double> c}.
 </pre></td></tr>
 
 
@@ -8140,18 +10899,20 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="throughUsingDecl0"><pre>Matches if a node refers to a declaration through a specific
 using shadow declaration.
 
-Examples:
+Given
   namespace a { int f(); }
   using a::f;
   int x = f();
-declRefExpr(throughUsingDecl(anything()))
-  matches f
+
+The matcher declRefExpr(throughUsingDecl(anything()))
+matches f
 
   namespace a { class X{}; }
   using a::X;
   X x;
-typeLoc(loc(usingType(throughUsingDecl(anything()))))
-  matches X
+
+The matcher typeLoc(loc(usingType(throughUsingDecl(anything()))))
+matches X
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UsingType.html">UsingType</a>>
 </pre></td></tr>
@@ -8161,10 +10922,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="to0"><pre>Matches a DeclRefExpr that refers to a declaration that matches the
 specified matcher.
 
-Example matches x in if(x)
-    (matcher = declRefExpr(to(varDecl(hasName("x")))))
-  bool x;
-  if (x) {}
+Given
+  void foo() {
+    bool x;
+    if (x) {}
+  }
+
+The matcher declRefExpr(to(varDecl(hasName("x"))))
+matches x inside the condition of the if-stmt.
 </pre></td></tr>
 
 
@@ -8174,16 +10939,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Note that this does not work for global declarations because the AST
 breaks up multiple-declaration DeclStmt's into multiple single-declaration
 DeclStmt's.
-Example: Given non-global declarations
-  int a, b = 0;
-  int c;
-  int d = 2, e;
-declStmt(containsDeclaration(
+
+Given non-global declarations
+  void foo() {
+    int a, b = 0;
+    int c;
+    int d = 2, e;
+  }
+The matcher declStmt(containsDeclaration(
       0, varDecl(hasInitializer(anything()))))
-  matches only 'int d = 2, e;', and
-declStmt(containsDeclaration(1, varDecl()))
-  matches 'int a, b = 0' as well as 'int d = 2, e;'
-  but 'int c;' is not matched.
+matches int d = 2, e;.
+The matcher declStmt(containsDeclaration(1, varDecl()))
+matches int a, b = 0; and int d = 2, e;
+but does not match int c;.
 </pre></td></tr>
 
 
@@ -8191,29 +10959,39 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasSingleDecl0"><pre>Matches the Decl of a DeclStmt which has a single declaration.
 
 Given
-  int a, b;
-  int c;
-declStmt(hasSingleDecl(anything()))
-  matches 'int c;' but not 'int a, b;'.
+  void foo() {
+    int a, b;
+    int c;
+  }
+The matcher declStmt(hasSingleDecl(anything()))
+matches int c;
+but does not match int a, b;
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclaratorDecl.html">DeclaratorDecl</a>></td><td class="name" onclick="toggle('hasTypeLoc8')"><a name="hasTypeLoc8Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc8"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -8237,8 +11015,9 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     }
   }
 
-cxxRcordDecl(hasDeclContext(namedDecl(hasName("M")))) matches the
-declaration of class D.
+
+The matcher cxxRecordDecl(hasDeclContext(namedDecl(hasName("M"))))
+  matches the declaration of D.
 </pre></td></tr>
 
 
@@ -8248,8 +11027,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   decltype(1) a = 1;
   decltype(2.0) b = 2.0;
-decltypeType(hasUnderlyingType(isInteger()))
-  matches the type of "a"
+
+
+The matcher decltypeType(hasUnderlyingType(isInteger()))
+matches the type decltype(1) of the variable
+declaration of a .
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DecltypeType.html">DecltypeType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UsingType.html">UsingType</a>>
 </pre></td></tr>
@@ -8266,16 +11048,17 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
     f = 42;
 }
-The matcher:
-  decompositionDecl(hasAnyBinding(bindingDecl(hasName("f").bind("fBinding"))))
-matches the decomposition decl with 'f' bound to "fBinding".
+
+The matcher
+ decompositionDecl(hasAnyBinding(bindingDecl(hasName("f")).bind("fBinding")))
+matches auto &[f, s, t] = arr with 'f' bound to "fBinding".
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DecompositionDecl.html">DecompositionDecl</a>></td><td class="name" onclick="toggle('hasBinding0')"><a name="hasBinding0Anchor">hasBinding</a></td><td>unsigned N, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BindingDecl.html">BindingDecl</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasBinding0"><pre>Matches the Nth binding of a DecompositionDecl.
 
-For example, in:
+Given
 void foo()
 {
     int arr[3];
@@ -8283,10 +11066,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
     f = 42;
 }
-The matcher:
-  decompositionDecl(hasBinding(0,
-  bindingDecl(hasName("f").bind("fBinding"))))
-matches the decomposition decl with 'f' bound to "fBinding".
+
+The matcher decompositionDecl(hasBinding(0,
+  bindingDecl(hasName("f")).bind("fBinding")))
+matches auto &[f, s, t] = arr with 'f' bound to "fBinding".
 </pre></td></tr>
 
 
@@ -8297,20 +11080,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 other declarations of the same function or coroutine.
 
 Given
+void foo() {
   for (;;) {}
-forStmt(hasBody(compoundStmt()))
-  matches 'for (;;) {}'
+}
+The matcher forStmt(hasBody(compoundStmt().bind("body")))
+matches for (;;) {}
 with compoundStmt()
-  matching '{}'
+  matching {}
 
 Given
   void f();
   void f() {}
-functionDecl(hasBody(compoundStmt()))
-  matches 'void f() {}'
+The matcher functionDecl(hasBody(compoundStmt().bind("compound")))
+f
 with compoundStmt()
-  matching '{}'
-  but does not match 'void f();'
+matching {}
+but does not match void f();
 </pre></td></tr>
 
 
@@ -8318,8 +11103,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasCondition3"><pre>Matches the condition expression of an if statement, for loop,
 switch statement or conditional operator.
 
-Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true))))
+Given
+void foo() {
   if (true) {}
+}
+
+The matcher ifStmt(hasCondition(cxxBoolLiteral(equals(true))))
+if (true) {}
 </pre></td></tr>
 
 
@@ -8334,14 +11124,16 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
   class D {};
   class D d;
-elaboratedTypeLoc(hasNamedTypeLoc(templateSpecializationTypeLoc()));
-  matches the `TypeLoc` of the variable declaration of `c`, but not `d`.
+
+The matcher
+elaboratedTypeLoc(hasNamedTypeLoc(templateSpecializationTypeLoc()))
+  matches class C<int>, but not D}
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ElaboratedType.html">ElaboratedType</a>></td><td class="name" onclick="toggle('hasQualifier0')"><a name="hasQualifier0Anchor">hasQualifier</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasQualifier0"><pre>Matches ElaboratedTypes whose qualifier, a NestedNameSpecifier,
-matches InnerMatcher if the qualifier exists.
+  matches InnerMatcher if the qualifier exists.
 
 Given
   namespace N {
@@ -8351,8 +11143,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   }
   N::M::D d;
 
-elaboratedType(hasQualifier(hasPrefix(specifiesNamespace(hasName("N"))))
-matches the type of the variable declaration of d.
+
+The matcher
+elaboratedType(hasQualifier(hasPrefix(specifiesNamespace(hasName("N")))))
+  matches the type N::M::D of the variable declaration
+  of d.
 </pre></td></tr>
 
 
@@ -8362,20 +11157,20 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   namespace N {
     namespace M {
-      class D {};
+      enum E { Ok };
     }
   }
-  N::M::D d;
+  N::M::E e = N::M::Ok;
 
-elaboratedType(namesType(recordType(
-hasDeclaration(namedDecl(hasName("D")))))) matches the type of the variable
-declaration of d.
+
+The matcher elaboratedType(namesType(enumType()))
+matches the type N::M::E of the declaration of e .
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>></td><td class="name" onclick="toggle('hasDeclaration10')"><a name="hasDeclaration10Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration10"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -8385,17 +11180,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -8412,25 +11215,37 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 (Note: Clang's AST refers to other conversions as "casts" too, and calls
 actual casts "explicit" casts.)
+
+  unsigned int a = (unsigned int)0;
+
+The matcher explicitCastExpr(hasDestinationType(
+qualType(isUnsignedInteger()))) matches (unsigned int)0.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ExplicitCastExpr.html">ExplicitCastExpr</a>></td><td class="name" onclick="toggle('hasTypeLoc9')"><a name="hasTypeLoc9Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc9"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -8453,21 +11268,31 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 X, while varDecl(hasType(cxxRecordDecl(hasName("X")))) matches the
 declaration of x.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              cxxRecordDecl(hasName("X"))))
  class X {};
  void y(X &x) { x; X z; }
  class Y { friend class X; };
  class Z : public virtual X {};
 
-Example matches class Derived
-(matcher = cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base"))))))
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z.
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X.
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches
+class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
+
+Given
 class Base {};
 class Derived : Base {};
 
+The matcher
+cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base")))))
+matches class Derived : Base {}.
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FriendDecl.html">FriendDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>>,
 Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>
 </pre></td></tr>
@@ -8477,17 +11302,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasType0"><pre>Matches if the expression's or declaration's type matches a type
 matcher.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and U (matcher = typedefDecl(hasType(asString("int")))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              asString("class X")))
+Exmaple
  class X {};
  void y(X &x) { x; X z; }
  typedef int U;
  class Y { friend class X; };
  class Z : public virtual X {};
+
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z
+The matcher typedefDecl(hasType(asString("int")))
+matches typedef int U
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
 </pre></td></tr>
 
 
@@ -8504,15 +11337,16 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 appear in the C++17 AST.
 
 Given
-
 struct H {};
 H G();
 void f() {
   H D = G();
 }
 
-``varDecl(hasInitializer(ignoringElidableConstructorCall(callExpr())))``
-matches ``H D = G()`` in C++11 through C++17 (and beyond).
+
+The matcher
+varDecl(hasInitializer(ignoringElidableConstructorCall(callExpr())))
+matches H D = G().
 </pre></td></tr>
 
 
@@ -8523,19 +11357,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Parentheses and explicit casts are not discarded.
 Given
   int arr[5];
-  int a = 0;
+  const int a = 0;
   char b = 0;
   const int c = a;
   int *d = arr;
   long e = (long) 0l;
-The matchers
-   varDecl(hasInitializer(ignoringImpCasts(integerLiteral())))
-   varDecl(hasInitializer(ignoringImpCasts(declRefExpr())))
-would match the declarations for a, b, c, and d, but not e.
-While
-   varDecl(hasInitializer(integerLiteral()))
-   varDecl(hasInitializer(declRefExpr()))
-only match the declarations for a.
+The matcher
+varDecl(hasInitializer(ignoringImpCasts(integerLiteral())))
+matches a and b,
+but does not match e.
+The matcher
+varDecl(hasInitializer(ignoringImpCasts(declRefExpr())))
+matches c and d.
+
+The matcher
+varDecl(hasInitializer(integerLiteral()))
+matches a,
+but does not match b or e.
+The matcher varDecl(hasInitializer(declRefExpr()))
+does not match c or d.
 </pre></td></tr>
 
 
@@ -8544,17 +11384,34 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 nodes are stripped off.
 
 Parentheses and explicit casts are not discarded.
+
 Given
-  class C {};
-  C a = C();
-  C b;
-  C c = b;
-The matchers
-   varDecl(hasInitializer(ignoringImplicit(cxxConstructExpr())))
-would match the declarations for a, b, and c.
-While
-   varDecl(hasInitializer(cxxConstructExpr()))
-only match the declarations for b and c.
+  void f(int param) {
+    int a = 0;
+    int b = param;
+    const int c = 0;
+    const int d = param;
+    int e = (0U);
+    int f = (int)0.0;
+    const int g = ((int)(((0))));
+  }
+
+The matcher
+varDecl(hasInitializer(ignoringImplicit(integerLiteral())))
+matches int a = 0 and const int c = 0,
+but not int e = (0U) and ((int)(((0))).
+The matcher
+varDecl(hasInitializer(integerLiteral()))
+matches int a = 0 and const int c = 0,
+but not int e = (0U) and ((int)(((0))).
+
+The matcher
+varDecl(hasInitializer(ignoringImplicit(declRefExpr())))
+matches int b = param and const int d = param.
+The matcher
+varDecl(hasInitializer(declRefExpr()))
+matches neither int b = param nor const int d = param,
+because an l-to-r-value cast happens.
 </pre></td></tr>
 
 
@@ -8568,12 +11425,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   char b = (0);
   void* c = reinterpret_cast<char*>(0);
   char d = char(0);
+
 The matcher
-   varDecl(hasInitializer(ignoringParenCasts(integerLiteral())))
-would match the declarations for a, b, c, and d.
-while
-   varDecl(hasInitializer(integerLiteral()))
-only match the declaration for a.
+varDecl(hasInitializer(ignoringParenCasts(integerLiteral())))
+matches a, b, c
+and d.
+The matcher
+varDecl(hasInitializer(integerLiteral()))
+matches a.
 </pre></td></tr>
 
 
@@ -8589,14 +11448,21 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   const int c = a;
   int *d = (arr);
   long e = ((long) 0l);
-The matchers
-   varDecl(hasInitializer(ignoringParenImpCasts(integerLiteral())))
-   varDecl(hasInitializer(ignoringParenImpCasts(declRefExpr())))
-would match the declarations for a, b, c, and d, but not e.
-while
-   varDecl(hasInitializer(integerLiteral()))
-   varDecl(hasInitializer(declRefExpr()))
-would only match the declaration for a.
+
+The matcher
+varDecl(hasInitializer(ignoringParenImpCasts(integerLiteral())))
+matches a and b,
+but does not match e.
+The matcher
+varDecl(hasInitializer(ignoringParenImpCasts(declRefExpr())))
+matches c and d.
+
+The matcher
+varDecl(hasInitializer(integerLiteral()))
+matches a,
+but does not match b or e.
+The matcher varDecl(hasInitializer(declRefExpr()))
+does not match c, or d.
 </pre></td></tr>
 
 
@@ -8606,8 +11472,9 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   const char* str = ("my-string");
 The matcher
-  implicitCastExpr(hasSourceExpression(ignoringParens(stringLiteral())))
-would match the implicit cast resulting from the assignment.
+implicitCastExpr(hasSourceExpression(ignoringParens(stringLiteral())))
+would match the implicit cast resulting from the assignment
+("my-string").
 </pre></td></tr>
 
 
@@ -8620,10 +11487,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     int b = 3;
     int c;
   };
+
+The matcher
 fieldDecl(hasInClassInitializer(integerLiteral(equals(2))))
-  matches 'int a;' but not 'int b;'.
-fieldDecl(hasInClassInitializer(anything()))
-  matches 'int a;' and 'int b;' but not 'int c;'.
+matches a,
+but does not match b.
+The matcher fieldDecl(hasInClassInitializer(anything()))
+matches a and b,
+but does not match c.
 </pre></td></tr>
 
 
@@ -8634,20 +11505,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 other declarations of the same function or coroutine.
 
 Given
+void foo() {
   for (;;) {}
-forStmt(hasBody(compoundStmt()))
-  matches 'for (;;) {}'
+}
+The matcher forStmt(hasBody(compoundStmt().bind("body")))
+matches for (;;) {}
 with compoundStmt()
-  matching '{}'
+  matching {}
 
 Given
   void f();
   void f() {}
-functionDecl(hasBody(compoundStmt()))
-  matches 'void f() {}'
+The matcher functionDecl(hasBody(compoundStmt().bind("compound")))
+f
 with compoundStmt()
-  matching '{}'
-  but does not match 'void f();'
+matching {}
+but does not match void f();
 </pre></td></tr>
 
 
@@ -8655,28 +11528,38 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasCondition1"><pre>Matches the condition expression of an if statement, for loop,
 switch statement or conditional operator.
 
-Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true))))
+Given
+void foo() {
   if (true) {}
+}
+
+The matcher ifStmt(hasCondition(cxxBoolLiteral(equals(true))))
+if (true) {}
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ForStmt.html">ForStmt</a>></td><td class="name" onclick="toggle('hasIncrement0')"><a name="hasIncrement0Anchor">hasIncrement</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasIncrement0"><pre>Matches the increment statement of a for loop.
 
-Example:
-    forStmt(hasIncrement(unaryOperator(hasOperatorName("++"))))
-matches '++x' in
-    for (x; x < N; ++x) { }
+Given
+void foo(int N) {
+    for (int x = 0; x < N; ++x) { }
+}
+The matcher
+forStmt(hasIncrement(unaryOperator(hasOperatorName("++"))))
+matches for (int x = 0; x < N; ++x) { }
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ForStmt.html">ForStmt</a>></td><td class="name" onclick="toggle('hasLoopInit0')"><a name="hasLoopInit0Anchor">hasLoopInit</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasLoopInit0"><pre>Matches the initialization statement of a for loop.
 
-Example:
-    forStmt(hasLoopInit(declStmt()))
-matches 'int x = 0' in
+Given
+void foo(int N) {
     for (int x = 0; x < N; ++x) { }
+}
+The matcher forStmt(hasLoopInit(declStmt()))
+matches for (int x = 0; x < N; ++x) { }
 </pre></td></tr>
 
 
@@ -8690,21 +11573,31 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 X, while varDecl(hasType(cxxRecordDecl(hasName("X")))) matches the
 declaration of x.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              cxxRecordDecl(hasName("X"))))
  class X {};
  void y(X &x) { x; X z; }
  class Y { friend class X; };
  class Z : public virtual X {};
 
-Example matches class Derived
-(matcher = cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base"))))))
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z.
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X.
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches
+class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
+
+Given
 class Base {};
 class Derived : Base {};
 
+The matcher
+cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base")))))
+matches class Derived : Base {}.
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FriendDecl.html">FriendDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>>,
 Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>
 </pre></td></tr>
@@ -8714,17 +11607,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasType1"><pre>Matches if the expression's or declaration's type matches a type
 matcher.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and U (matcher = typedefDecl(hasType(asString("int")))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              asString("class X")))
+Exmaple
  class X {};
  void y(X &x) { x; X z; }
  typedef int U;
  class Y { friend class X; };
  class Z : public virtual X {};
+
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z
+The matcher typedefDecl(hasType(asString("int")))
+matches typedef int U
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
 </pre></td></tr>
 
 
@@ -8744,13 +11645,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template <typename T, typename U>
   void f(T&& t, U&& u) {}
 
-  bool B = false;
-  f(R, B);
-templateSpecializationType(forEachTemplateArgument(isExpr(expr())))
-  matches twice, with expr() matching 'R * 2' and 'R * 4'
-functionDecl(forEachTemplateArgument(refersToType(builtinType())))
-  matches the specialization f<unsigned, bool> twice, for 'unsigned'
-  and 'bool'
+  void foo() {
+    bool B = false;
+    f(R, B);
+  }
+
+The matcher
+templateSpecializationType(forEachTemplateArgument(isExpr(expr().bind("t_arg"))))
+matches Matrix<int, R * 2, R * 4> twice, with
+expr() matching R * 2 and
+R * 4.
+The matcher
+functionDecl(forEachTemplateArgument(refersToType(qualType().bind("type"))))
+matches the specialization of f twice,
+with qualType() matching
+unsigned and
+bool.
 </pre></td></tr>
 
 
@@ -8763,12 +11673,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   void f();
   void f() {}
   void g();
-functionDecl(hasAnyBody(compoundStmt()))
-  matches both 'void f();'
-  and 'void f() {}'
+The matcher functionDecl(hasAnyBody(compoundStmt()))
+  matches f
+  and f
 with compoundStmt()
-  matching '{}'
-  but does not match 'void g();'
+  matching {}
+  but does not match void g();
 </pre></td></tr>
 
 
@@ -8780,23 +11690,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   class X { void f(int x, int y, int z) {} };
-cxxMethodDecl(hasAnyParameter(hasName("y")))
-  matches f(int x, int y, int z) {}
+
+The matcher cxxMethodDecl(hasAnyParameter(hasName("y")))
+  matches f
 with hasAnyParameter(...)
   matching int y
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
 
+
 the matcher objcMethodDecl(hasAnyParameter(hasName("y")))
-matches the declaration of method f with hasParameter
+  matches the declaration of method f with hasParameter
 matching y.
 
 For blocks, given
   b = ^(int y) { printf("%d", y) };
 
+
 the matcher blockDecl(hasAnyParameter(hasName("y")))
-matches the declaration of the block b with hasParameter
+  matches the declaration of the block b with hasParameter
 matching y.
 </pre></td></tr>
 
@@ -8810,9 +11723,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   template<typename T> class A {};
   A<int> a;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
-  hasTypeLoc(loc(asString("int")))))))
-  matches `A<int> a`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
+hasTypeLoc(loc(asString("int"))))))))) matches A<int> a.
 </pre></td></tr>
 
 
@@ -8826,15 +11741,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<> class A<double> {};
   A<int> a;
 
-  template<typename T> f() {};
+  template<typename T> void f() {};
   void func() { f<int>(); };
 
-classTemplateSpecializationDecl(hasAnyTemplateArgument(
-    refersToType(asString("int"))))
-  matches the specialization A<int>
 
-functionDecl(hasAnyTemplateArgument(refersToType(asString("int"))))
-  matches the specialization f<int>
+The matcher classTemplateSpecializationDecl(
+                        hasAnyTemplateArgument(
+                          refersToType(asString("int"))))
+matches class A<int>.
+
+The matcher
+functionDecl(hasAnyTemplateArgument(
+              refersToType(asString("int"))))
+matches the instantiation of f.
 </pre></td></tr>
 
 
@@ -8845,20 +11764,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 other declarations of the same function or coroutine.
 
 Given
+void foo() {
   for (;;) {}
-forStmt(hasBody(compoundStmt()))
-  matches 'for (;;) {}'
+}
+The matcher forStmt(hasBody(compoundStmt().bind("body")))
+matches for (;;) {}
 with compoundStmt()
-  matching '{}'
+  matching {}
 
 Given
   void f();
   void f() {}
-functionDecl(hasBody(compoundStmt()))
-  matches 'void f() {}'
+The matcher functionDecl(hasBody(compoundStmt().bind("compound")))
+f
 with compoundStmt()
-  matching '{}'
-  but does not match 'void f();'
+matching {}
+but does not match void f();
 </pre></td></tr>
 
 
@@ -8873,15 +11794,27 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     explicit S(double); // #2
     operator int(); // #3
     explicit operator bool(); // #4
-    explicit(false) S(bool) // # 7
-    explicit(true) S(char) // # 8
-    explicit(b) S(S) // # 9
+    explicit(false) S(bool); // # 7
+    explicit(true) S(char); // # 8
+    explicit(b) S(float); // # 9
   };
-  S(int) -> S<true> // #5
-  explicit S(double) -> S<false> // #6
-cxxConstructorDecl(hasExplicitSpecifier(constantExpr())) will match #7, #8 and #9, but not #1 or #2.
-cxxConversionDecl(hasExplicitSpecifier(constantExpr())) will not match #3 or #4.
-cxxDeductionGuideDecl(hasExplicitSpecifier(constantExpr())) will not match #5 or #6.
+  S(int) -> S<true>; // #5
+  explicit S(double) -> S<false>; // #6
+
+The matcher
+cxxConstructorDecl(hasExplicitSpecifier(constantExpr())) matches
+explicit(false) S(bool) and explicit(true) S(char),
+but does not match explicit(b) S(float), S(int) or
+explicit S(double).
+The matcher
+cxxConversionDecl(hasExplicitSpecifier(constantExpr())) does not
+match operator int() or explicit operator bool().
+Matcher
+The matcher
+cxxDeductionGuideDecl(hasExplicitSpecifier(declRefExpr()))
+matches the implicitly generated deduction guide
+auto (float) -> S<b> of the constructor
+S(float)}.
 </pre></td></tr>
 
 
@@ -8891,15 +11824,18 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   class X { void f(int x) {} };
-cxxMethodDecl(hasParameter(0, hasType(varDecl())))
-  matches f(int x) {}
+
+The matcher
+cxxMethodDecl(hasParameter(0, hasType(asString("int"))))
+matches f
 with hasParameter(...)
-  matching int x
+matching int x.
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
 
-the matcher objcMethodDecl(hasParameter(0, hasName("y")))
+
+The matcher objcMethodDecl(hasParameter(0, hasName("y")))
 matches the declaration of method f with hasParameter
 matching y.
 </pre></td></tr>
@@ -8911,9 +11847,9 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   int f() { return 5; }
   void g() {}
-functionDecl(hasReturnTypeLoc(loc(asString("int"))))
-  matches the declaration of `f`, but not `g`.
-</pre></td></tr>
+The matcher functionDecl(hasReturnTypeLoc(loc(asString("int"))))
+  matches the declaration of f, but not
+  </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasTemplateArgumentLoc2')"><a name="hasTemplateArgumentLoc2Anchor">hasTemplateArgumentLoc</a></td><td>unsigned Index, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TemplateArgumentLoc.html">TemplateArgumentLoc</a>> InnerMatcher</td></tr>
@@ -8925,9 +11861,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<typename T, typename U> class A {};
   A<double, int> b;
   A<int, double> c;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
-  hasTypeLoc(loc(asString("double")))))))
-  matches `A<double, int> b`, but not `A<int, double> c`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
+hasTypeLoc(loc(asString("double")))))))))
+matches A<double, int> b, but not double> c}.
 </pre></td></tr>
 
 
@@ -8938,27 +11877,31 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   template<typename T, typename U> class A {};
-  A<bool, int> b;
-  A<int, bool> c;
+  A<double, int> b;
+  A<int, double> c;
 
   template<typename T> void f() {}
   void func() { f<int>(); };
+
+The matcher
 classTemplateSpecializationDecl(hasTemplateArgument(
     1, refersToType(asString("int"))))
-  matches the specialization A<bool, int>
+matches the specialization class A<double, int>.
 
-functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
-  matches the specialization f<int>
+The matcher functionDecl(hasTemplateArgument(0,
+                        refersToType(asString("int"))))
+matches the specialization of f.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('returns0')"><a name="returns0Anchor">returns</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="returns0"><pre>Matches the return type of a function declaration.
 
-Given:
+Given
   class X { int f() { return 1; } };
-cxxMethodDecl(returns(asString("int")))
-  matches int f() { return 1; }
+
+The matcher cxxMethodDecl(returns(asString("int")))
+  matches f
 </pre></td></tr>
 
 
@@ -8966,8 +11909,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasCondition0"><pre>Matches the condition expression of an if statement, for loop,
 switch statement or conditional operator.
 
-Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true))))
+Given
+void foo() {
   if (true) {}
+}
+
+The matcher ifStmt(hasCondition(cxxBoolLiteral(equals(true))))
+if (true) {}
 </pre></td></tr>
 
 
@@ -8975,25 +11923,37 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasConditionVariableStatement0"><pre>Matches the condition variable statement in an if statement.
 
 Given
+struct A {};
+A* GetAPointer();
+void foo() {
   if (A* a = GetAPointer()) {}
-hasConditionVariableStatement(...)
-  matches 'A* a = GetAPointer()'.
+}
+
+The matcher ifStmt(hasConditionVariableStatement(declStmt()))
+if (A* a = GetAPointer()) {}
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasElse0')"><a name="hasElse0Anchor">hasElse</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasElse0"><pre>Matches the else-statement of an if statement.
 
-Examples matches the if statement
-  (matcher = ifStmt(hasElse(cxxBoolLiteral(equals(true)))))
+Given
+void foo() {
   if (false) false; else true;
+}
+
+The matcher ifStmt(hasElse(cxxBoolLiteral(equals(true))))
+if (false) false; else true
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasInitStatement0')"><a name="hasInitStatement0Anchor">hasInitStatement</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasInitStatement0"><pre>Matches selection statements with initializer.
 
-Given:
+Given
+ struct vec { int* begin(); int* end(); };
+ int foobar();
+ vec& get_range();
  void foo() {
    if (int i = foobar(); i > 0) {}
    switch (int i = foobar(); i) {}
@@ -9004,48 +11964,77 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
    switch (foobar()) {}
    for (auto& x : get_range()) {}
  }
-ifStmt(hasInitStatement(anything()))
-  matches the if statement in foo but not in bar.
-switchStmt(hasInitStatement(anything()))
-  matches the switch statement in foo but not in bar.
-cxxForRangeStmt(hasInitStatement(anything()))
-  matches the range for statement in foo but not in bar.
+
+The matcher ifStmt(hasInitStatement(anything()))
+  matches the if statement if (int i = foobar(); i > 0) {}
+  in foo but not if (foobar() > 0) {} in bar.
+The matcher switchStmt(hasInitStatement(anything()))
+  matches the switch statement switch (int i = foobar(); i) {}
+  in foo but not switch (foobar()) {} in bar.
+The matcher cxxForRangeStmt(hasInitStatement(anything()))
+  matches the range for statement
+  for (auto& a = get_range(); auto& x : a) {} in foo
+  but not for (auto& x : get_range()) {} in bar.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasThen0')"><a name="hasThen0Anchor">hasThen</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasThen0"><pre>Matches the then-statement of an if statement.
 
-Examples matches the if statement
-  (matcher = ifStmt(hasThen(cxxBoolLiteral(equals(true)))))
+Given
+void foo() {
   if (false) true; else false;
+}
+
+The matcher ifStmt(hasThen(cxxBoolLiteral(equals(true))))
+if (false) true; else false
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ImplicitCastExpr.html">ImplicitCastExpr</a>></td><td class="name" onclick="toggle('hasImplicitDestinationType0')"><a name="hasImplicitDestinationType0Anchor">hasImplicitDestinationType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasImplicitDestinationType0"><pre>Matches implicit casts whose destination type matches a given
 matcher.
+
+Given
+  unsigned int a = 0;
+
+The matcher
+implicitCastExpr(hasImplicitDestinationType(
+qualType(isUnsignedInteger()))) matches 0.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1InitListExpr.html">InitListExpr</a>></td><td class="name" onclick="toggle('hasInit0')"><a name="hasInit0Anchor">hasInit</a></td><td>unsigned N, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasInit0"><pre>Matches the n'th item of an initializer list expression.
 
-Example matches y.
-    (matcher = initListExpr(hasInit(0, expr())))
-  int x{y}.
+Given
+  int y = 42;
+  int x{y};
+
+The matcher initListExpr(hasInit(0, expr()))
+matches {y}.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1InitListExpr.html">InitListExpr</a>></td><td class="name" onclick="toggle('hasSyntacticForm0')"><a name="hasSyntacticForm0Anchor">hasSyntacticForm</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasSyntacticForm0"><pre>Matches the syntactic form of init list expressions
 (if expression have it).
+
+Given
+  int a[] = { 1, 2 };
+  struct B { int x, y; };
+  struct B b = { 5, 6 };
+
+
+The matcher
+initListExpr(hasSyntacticForm(expr().bind("syntactic")))
+matches { 1, 2 } and { 5, 6 }.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>></td><td class="name" onclick="toggle('hasDeclaration9')"><a name="hasDeclaration9Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration9"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -9055,17 +12044,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -9079,7 +12076,7 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>></td><td class="name" onclick="toggle('hasDeclaration8')"><a name="hasDeclaration8Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration8"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -9089,17 +12086,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -9122,9 +12127,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     auto f = [x](){};
     auto g = [x = 1](){};
   }
-In the matcher
-lambdaExpr(hasAnyCapture(lambdaCapture(capturesVar(hasName("x")))),
-capturesVar(hasName("x")) matches `x` and `x = 1`.
+
+The matcher
+lambdaExpr(hasAnyCapture(
+    lambdaCapture(capturesVar(hasName("x"))).bind("capture")))
+matches [x](){} and [x = 1](){}, with
+lambdaCapture(capturesVar(hasName("x"))).bind("capture")
+matching x and x = 1.
 </pre></td></tr>
 
 
@@ -9133,13 +12142,18 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   int main() {
-    int x, y;
+    int x;
+    int y;
     float z;
     auto f = [=]() { return x + y + z; };
   }
-lambdaExpr(forEachLambdaCapture(
-    lambdaCapture(capturesVar(varDecl(hasType(isInteger()))))))
-will trigger two matches, binding for 'x' and 'y' respectively.
+
+The matcher lambdaExpr(forEachLambdaCapture(
+    lambdaCapture(capturesVar(
+    varDecl(hasType(isInteger())).bind("captured")))))
+matches [=]() { return x + y + z; } two times,
+with varDecl(hasType(isInteger())) matching
+int x and int y.
 </pre></td></tr>
 
 
@@ -9151,15 +12165,16 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     int t = 5;
     auto f = [=](){ return t; };
   }
-lambdaExpr(hasAnyCapture(lambdaCapture())) and
-lambdaExpr(hasAnyCapture(lambdaCapture(refersToVarDecl(hasName("t")))))
-  both match `[=](){ return t; }`.
+
+The matcher lambdaExpr(hasAnyCapture(lambdaCapture())) and
+lambdaExpr(hasAnyCapture(lambdaCapture(capturesVar(hasName("t")))))
+  both match [=](){ return t; }.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>></td><td class="name" onclick="toggle('hasDeclaration7')"><a name="hasDeclaration7Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration7"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -9169,17 +12184,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -9201,11 +12224,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     int m;
     int f(X x) { x.m; return m; }
   };
+
+
+The matcher
 memberExpr(hasObjectExpression(hasType(cxxRecordDecl(hasName("X")))))
-  matches `x.m`, but not `m`; however,
-memberExpr(hasObjectExpression(hasType(pointsTo(
-     cxxRecordDecl(hasName("X"))))))
-  matches `m` (aka. `this->m`), but not `x.m`.
+matches x.m, but not m; however,
+The matcher memberExpr(hasObjectExpression(hasType(pointsTo(
+cxxRecordDecl(hasName("X"))))))
+matches m (aka. this->m), but not x.m.
 </pre></td></tr>
 
 
@@ -9214,13 +12240,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 given matcher.
 
 Given
-  struct { int first, second; } first, second;
-  int i(second.first);
-  int j(first.second);
-memberExpr(member(hasName("first")))
-  matches second.first
-  but not first.second (because the member name there is "second").
-</pre></td></tr>
+  struct { int first = 0, second = 1; } first, second;
+  int i = second.first;
+  int j = first.second;
+
+
+The matcher memberExpr(member(hasName("first")))
+matches second.first
+but not </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>></td><td class="name" onclick="toggle('pointee1')"><a name="pointee1Anchor">pointee</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
@@ -9229,10 +12256,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   int *a;
-  int const *b;
-  float const *f;
-pointerType(pointee(isConstQualified(), isInteger()))
-  matches "int const *b"
+  const int *b;
+  int * const c = nullptr;
+  const float *f;
+
+The matcher pointerType(pointee(isConstQualified(), isInteger()))
+matches const int *,
+but does not match int * const
+or const float *.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
@@ -9246,9 +12277,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   namespace N { template<class T> void f(T t); }
   template <class T> void g() { using N::f; f(T()); }
-unresolvedLookupExpr(hasAnyDeclaration(
+
+The matcher unresolvedLookupExpr(hasAnyDeclaration(
     namedDecl(hasUnderlyingDecl(hasName("::N::f")))))
-  matches the use of f in g() .
+  matches f in g().
 </pre></td></tr>
 
 
@@ -9258,14 +12290,29 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   struct A { struct B { struct C {}; }; };
   A::B::C c;
-nestedNameSpecifierLoc(hasPrefix(loc(specifiesType(asString("struct A")))))
-  matches "A::"
+
+The matcher
+nestedNameSpecifierLoc(hasPrefix(loc(specifiesType(asString(
+"struct A"))))) matches A::B::.
 </pre></td></tr>
 
 
-<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>></td><td class="name" onclick="toggle('loc1')"><a name="loc1Anchor">loc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>> InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="loc1"><pre>Matches NestedNameSpecifierLocs for which the given inner
-NestedNameSpecifier-matcher matches.
+<tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>></td><td class="name" onclick="toggle('loc1')"><a name="loc1Anchor">loc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="loc1"><pre>Matches NestedNameSpecifierLocs for which the given inner
+NestedNameSpecifier-matcher matches.
+
+Given
+  namespace ns {
+    struct A { static void f(); };
+    void A::f() {}
+    void g() { A::f(); }
+  }
+  ns::A a;
+
+
+The matcher nestedNameSpecifierLoc(loc(specifiesType(
+hasDeclaration(namedDecl(hasName("A")))))) matches A::
+twice.
 </pre></td></tr>
 
 
@@ -9276,9 +12323,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   struct A { struct B { struct C {}; }; };
   A::B::C c;
-nestedNameSpecifierLoc(specifiesTypeLoc(loc(type(
+
+The matcher nestedNameSpecifierLoc(specifiesTypeLoc(loc(qualType(
   hasDeclaration(cxxRecordDecl(hasName("A")))))))
-  matches "A::"
+matches A::
 </pre></td></tr>
 
 
@@ -9288,8 +12336,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   struct A { struct B { struct C {}; }; };
   A::B::C c;
-nestedNameSpecifier(hasPrefix(specifiesType(asString("struct A")))) and
-  matches "A::"
+
+The matcher
+nestedNameSpecifier(hasPrefix(specifiesType(asString(
+"struct A")))) matches struct A::B
 </pre></td></tr>
 
 
@@ -9300,8 +12350,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   namespace ns { struct A {}; }
   ns::A a;
-nestedNameSpecifier(specifiesNamespace(hasName("ns")))
-  matches "ns::"
+
+The matcher
+nestedNameSpecifier(specifiesNamespace(hasName("ns"))) matches
+ns.
 </pre></td></tr>
 
 
@@ -9312,10 +12364,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   struct A { struct B { struct C {}; }; };
   A::B::C c;
-nestedNameSpecifier(specifiesType(
+
+The matcher nestedNameSpecifier(specifiesType(
   hasDeclaration(cxxRecordDecl(hasName("A")))
 ))
-  matches "A::"
+matches A.
 </pre></td></tr>
 
 
@@ -9323,12 +12376,16 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasAnyClause0"><pre>Matches any clause in an OpenMP directive.
 
 Given
-
+  void foo() {
   #pragma omp parallel
+    ;
   #pragma omp parallel default(none)
+    ;
+  }
 
-``ompExecutableDirective(hasAnyClause(anything()))`` matches
-``omp parallel default(none)``.
+
+The matcher ompExecutableDirective(hasAnyClause(anything()))
+matches #pragma omp parallel default(none).
 </pre></td></tr>
 
 
@@ -9339,13 +12396,18 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 If it is, it will never match.
 
 Given
+  void foo() {
+    #pragma omp parallel
+    ;
+    #pragma omp parallel
+    {}
+  }
 
-   #pragma omp parallel
-   ;
-   #pragma omp parallel
-   {}
 
-``ompExecutableDirective(hasStructuredBlock(nullStmt()))`` will match ``;``
+The matcher
+ompExecutableDirective(hasStructuredBlock(nullStmt().bind("stmt")))
+matches #pragma omp parallel,
+with stmtt() matching {}.
 </pre></td></tr>
 
 
@@ -9357,22 +12419,29 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Note that a class is not considered to be derived from itself.
 
 Example matches Y, Z, C (Base == hasName("X"))
-  class X;
+  class X {};
   class Y : public X {};  // directly derived
   class Z : public Y {};  // indirectly derived
   typedef X A;
   typedef A B;
   class C : public B {};  // derived from a typedef of X
 
-In the following example, Bar matches isDerivedFrom(hasName("X")):
-  class Foo;
-  typedef Foo X;
-  class Bar : public Foo {};  // derived from a type that X is a typedef of
+  class Foo {};
+  typedef Foo Alias;
+  class Bar : public Alias {};
+  // derived from a type that Alias is a typedef of Foo
+
+
+The matcher cxxRecordDecl(isDerivedFrom(hasName("X")))
+matches Y, Z and C.
+The matcher cxxRecordDecl(isDerivedFrom(hasName("Foo")))
+matches Bar.
 
 In the following example, Bar matches isDerivedFrom(hasName("NSObject"))
   @interface NSObject @end
   @interface Bar : NSObject @end
 
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCInterfaceDecl.html">ObjCInterfaceDecl</a>>
 </pre></td></tr>
 
@@ -9383,24 +12452,45 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Note that a class is not considered to be derived from itself.
 
-Example matches Y, C (Base == hasName("X"))
-  class X;
+Given
+  class X {};
   class Y : public X {};  // directly derived
   class Z : public Y {};  // indirectly derived
   typedef X A;
   typedef A B;
   class C : public B {};  // derived from a typedef of X
 
+The matcher
+cxxRecordDecl(isDirectlyDerivedFrom(namedDecl(hasName("X"))))
+matches Y and C (Base == hasName("X")
+
 In the following example, Bar matches isDerivedFrom(hasName("X")):
-  class Foo;
+  class Foo {};
   typedef Foo X;
   class Bar : public Foo {};  // derived from a type that X is a typedef of
+
+The matcher cxxRecordDecl(isDerivedFrom(hasName("X")))
+matches Bar
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCInterfaceDecl.html">ObjCInterfaceDecl</a>></td><td class="name" onclick="toggle('isSameOrDerivedFrom1')"><a name="isSameOrDerivedFrom1Anchor">isSameOrDerivedFrom</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>> Base</td></tr>
 <tr><td colspan="4" class="doc" id="isSameOrDerivedFrom1"><pre>Similar to isDerivedFrom(), but also matches classes that directly
 match Base.
+
+Given
+  class X {};
+  class Y : public X {};  // directly derived
+  class Z : public Y {};  // indirectly derived
+  typedef X A;
+  typedef A B;
+  class C : public B {};  // derived from a typedef of X
+
+The matcher
+cxxRecordDecl(isSameOrDerivedFrom(cxxRecordDecl(hasName("X"))),
+isDefinition())
+matches class X {}, class Y : public X {},
+class Z : public Y {} and class C : public B {}.
 </pre></td></tr>
 
 
@@ -9409,19 +12499,23 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 given matcher; or 2) if the Obj-C message expression's callee's method
 declaration matches the given matcher.
 
-Example matches y.x() (matcher = callExpr(callee(
-                                   cxxMethodDecl(hasName("x")))))
+Example 1
   class Y { public: void x(); };
   void z() { Y y; y.x(); }
 
-Example 2. Matches [I foo] with
-objcMessageExpr(callee(objcMethodDecl(hasName("foo"))))
+The matcher callExpr(callee(cxxMethodDecl(hasName("x"))))
+matches y.x()
 
+Example 2
   @interface I: NSObject
   +(void)foo;
   @end
   ...
   [I foo]
+
+The matcher
+objcMessageExpr(callee(objcMethodDecl(hasName("foo"))))
+matches [I foo]
 </pre></td></tr>
 
 
@@ -9430,17 +12524,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 expression, or an ObjC-message-send expression.
 
 Given
-  void x(int, int, int) { int y; x(1, y, 42); }
-callExpr(hasAnyArgument(declRefExpr()))
-  matches x(1, y, 42)
-with hasAnyArgument(...)
+  void x(int, int, int) { int y = 42; x(1, y, 42); }
+The matcher
+callExpr(hasAnyArgument(ignoringImplicit(declRefExpr()))) matches
+x(1, y, 42) with hasAnyArgument(...)
   matching y
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
   void foo(I *i) { [i f:12]; }
+
+The matcher
 objcMessageExpr(hasAnyArgument(integerLiteral(equals(12))))
-  matches [i f:12]
+matches [i f:12]
 </pre></td></tr>
 
 
@@ -9448,9 +12544,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasArgument3"><pre>Matches the n'th argument of a call expression or a constructor
 call expression.
 
-Example matches y in x(y)
-    (matcher = callExpr(hasArgument(0, declRefExpr())))
+Given
   void x(int) { int y; x(y); }
+The matcher callExpr(hasArgument(0, declRefExpr().bind("arg")))
+matches x(y),
+with declRefExpr() matching y.
 </pre></td></tr>
 
 
@@ -9458,23 +12556,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasReceiver0"><pre>Matches if the Objective-C message is sent to an instance,
 and the inner matcher matches on that instance.
 
-For example the method call in
+Given
   NSString *x = @"hello";
   [x containsString:@"h"];
-is matched by
+
+The matcher
 objcMessageExpr(hasReceiver(declRefExpr(to(varDecl(hasName("x"))))))
+matches [x containsString:@"h"];
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('hasReceiverType0')"><a name="hasReceiverType0Anchor">hasReceiverType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasReceiverType0"><pre>Matches on the receiver of an ObjectiveC Message expression.
 
-Example
-matcher = objCMessageExpr(hasReceiverType(asString("UIWebView *")));
-matches the [webView ...] message invocation.
   NSString *webViewJavaScript = ...
   UIWebView *webView = ...
   [webView stringByEvaluatingJavaScriptFromString:webViewJavascript];
+
+The matcher objCMessageExpr(hasReceiverType(asString("UIWebView
+*"))) matches
+[webViewstringByEvaluatingJavaScriptFromString:webViewJavascript];
 </pre></td></tr>
 
 
@@ -9486,23 +12587,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   class X { void f(int x, int y, int z) {} };
-cxxMethodDecl(hasAnyParameter(hasName("y")))
-  matches f(int x, int y, int z) {}
+
+The matcher cxxMethodDecl(hasAnyParameter(hasName("y")))
+  matches f
 with hasAnyParameter(...)
   matching int y
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
 
+
 the matcher objcMethodDecl(hasAnyParameter(hasName("y")))
-matches the declaration of method f with hasParameter
+  matches the declaration of method f with hasParameter
 matching y.
 
 For blocks, given
   b = ^(int y) { printf("%d", y) };
 
+
 the matcher blockDecl(hasAnyParameter(hasName("y")))
-matches the declaration of the block b with hasParameter
+  matches the declaration of the block b with hasParameter
 matching y.
 </pre></td></tr>
 
@@ -9513,15 +12617,18 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   class X { void f(int x) {} };
-cxxMethodDecl(hasParameter(0, hasType(varDecl())))
-  matches f(int x) {}
+
+The matcher
+cxxMethodDecl(hasParameter(0, hasType(asString("int"))))
+matches f
 with hasParameter(...)
-  matching int x
+matching int x.
 
 For ObjectiveC, given
   @interface I - (void) f:(int) y; @end
 
-the matcher objcMethodDecl(hasParameter(0, hasName("y")))
+
+The matcher objcMethodDecl(hasParameter(0, hasName("y")))
 matches the declaration of method f with hasParameter
 matching y.
 </pre></td></tr>
@@ -9530,19 +12637,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCPropertyDecl.html">ObjCPropertyDecl</a>></td><td class="name" onclick="toggle('hasTypeLoc10')"><a name="hasTypeLoc10Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc10"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -9559,14 +12673,23 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasSourceExpression1"><pre>Matches if the cast's source expression
 or opaque value's source expression matches the given matcher.
 
-Example 1: matches "a string"
-(matcher = castExpr(hasSourceExpression(cxxConstructExpr())))
-class URL { URL(string); };
-URL url = "a string";
+Given
+ struct URL { URL(const char*); };
+ URL url = "a string";
+
+The matcher castExpr(hasSourceExpression(cxxConstructExpr()))
+matches "a string".
 
-Example 2: matches 'b' (matcher =
-opaqueValueExpr(hasSourceExpression(implicitCastExpr(declRefExpr())))
-int a = b ?: 1;
+Given
+void foo(bool b) {
+  int a = b ?: 1;
+}
+
+The matcher
+opaqueValueExpr(hasSourceExpression(
+              implicitCastExpr(has(
+                implicitCastExpr(has(declRefExpr()))))))
+matches b twice, for the conditiona and the true expression.
 </pre></td></tr>
 
 
@@ -9581,9 +12704,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     foo(t);
     bar(t);
   }
-unresolvedLookupExpr(hasAnyDeclaration(
+
+The matcher unresolvedLookupExpr(hasAnyDeclaration(
     functionTemplateDecl(hasName("foo"))))
-  matches foo in foo(t); but not bar in bar(t);
+matches foo in foo(t);
+but does not match bar in bar(t);
 </pre></td></tr>
 
 
@@ -9594,8 +12719,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   int (*ptr_to_array)[4];
   int (*ptr_to_func)(int);
 
-varDecl(hasType(pointsTo(parenType(innerType(functionType()))))) matches
-ptr_to_func but not ptr_to_array.
+The matcher
+varDecl(hasType(pointsTo(parenType(innerType(functionType())))))
+  matches ptr_to_func but not
+  ptr_to_array.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ParenType.html">ParenType</a>>
 </pre></td></tr>
@@ -9607,8 +12734,8 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   int* x;
-pointerTypeLoc(hasPointeeLoc(loc(asString("int"))))
-  matches `int*`.
+The matcher pointerTypeLoc(hasPointeeLoc(loc(asString("int"))))
+  matches int*.
 </pre></td></tr>
 
 
@@ -9618,10 +12745,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   int *a;
-  int const *b;
-  float const *f;
-pointerType(pointee(isConstQualified(), isInteger()))
-  matches "int const *b"
+  const int *b;
+  int * const c = nullptr;
+  const float *f;
+
+The matcher pointerType(pointee(isConstQualified(), isInteger()))
+matches const int *,
+but does not match int * const
+or const float *.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
@@ -9631,19 +12762,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('hasCanonicalType0')"><a name="hasCanonicalType0Anchor">hasCanonicalType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasCanonicalType0"><pre>Matches QualTypes whose canonical type matches InnerMatcher.
 
-Given:
+Given
   typedef int &int_ref;
   int a;
   int_ref b = a;
 
-varDecl(hasType(qualType(referenceType()))))) will not match the
-declaration of b but varDecl(hasType(qualType(hasCanonicalType(referenceType())))))) does.
+The matcher varDecl(hasType(qualType(referenceType())))
+does not match int_ref b = a,
+but the matcher
+varDecl(hasType(qualType(hasCanonicalType(referenceType()))))
+does match int_ref b = a.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('hasDeclaration6')"><a name="hasDeclaration6Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration6"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -9653,17 +12787,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -9681,30 +12823,56 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   void (*fp)(void);
 The matcher
-  varDecl(hasType(pointerType(pointee(ignoringParens(functionType())))))
-would match the declaration for fp.
+varDecl(hasType(pointerType(pointee(ignoringParens(functionType())))))
+matches fp.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('pointsTo1')"><a name="pointsTo1Anchor">pointsTo</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="pointsTo1"><pre>Overloaded to match the pointee type's declaration.
+<tr><td colspan="4" class="doc" id="pointsTo1"><pre>Matches if the matched type is a pointer type and the pointee type
+  matches the specified matcher.
+Overloaded to match the pointee type's declaration.
+
+Given
+  class Y { public: void x(); };
+  void z() { Y *y; y->x(); }
+
+The matcher cxxMemberCallExpr(on(hasType(pointsTo(
+     cxxRecordDecl(hasName("Y"))))))
+matches y->x()
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('pointsTo0')"><a name="pointsTo0Anchor">pointsTo</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="pointsTo0"><pre>Matches if the matched type is a pointer type and the pointee type
-matches the specified matcher.
+  matches the specified matcher.
 
-Example matches y->x()
-  (matcher = cxxMemberCallExpr(on(hasType(pointsTo
-     cxxRecordDecl(hasName("Y")))))))
+Given
   class Y { public: void x(); };
   void z() { Y *y; y->x(); }
+
+The matcher cxxMemberCallExpr(on(hasType(pointsTo(
+     qualType()))))
+matches y->x()
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('references1')"><a name="references1Anchor">references</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="references1"><pre>Overloaded to match the referenced type's declaration.
+<tr><td colspan="4" class="doc" id="references1"><pre>Matches if the matched type is a reference type and the referenced
+type matches the specified matcher.
+Overloaded to match the referenced type's declaration.
+
+Given
+  class X {
+    void a(X b) {
+      X &x = b;
+      const X &y = b;
+    }
+  };
+
+The matcher
+varDecl(hasType(references(cxxRecordDecl(hasName("X"))))) matches
+X &x = b and const X &y = b.
 </pre></td></tr>
 
 
@@ -9712,14 +12880,17 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="references0"><pre>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(cxxRecordDecl(hasName("X"))))))
+Given
   class X {
     void a(X b) {
       X &x = b;
       const X &y = b;
     }
   };
+
+The matcher
+varDecl(hasType(references(qualType()))) matches
+X &x = b and const X &y = b.
 </pre></td></tr>
 
 
@@ -9728,16 +12899,18 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 `InnerMatcher`.
 
 Given
-  int* const x;
-  const int y;
-qualifiedTypeLoc(hasUnqualifiedLoc(pointerTypeLoc()))
-  matches the `TypeLoc` of the variable declaration of `x`, but not `y`.
-</pre></td></tr>
+  int* const x = nullptr;
+  const int y = 0;
+
+
+The matcher qualifiedTypeLoc(hasUnqualifiedLoc(pointerTypeLoc()))
+matches the type int* of the variable declaration but
+not </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>></td><td class="name" onclick="toggle('hasDeclaration5')"><a name="hasDeclaration5Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration5"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -9747,17 +12920,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -9776,8 +12957,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   int x = 3;
   int& xx = x;
-referenceTypeLoc(hasReferentLoc(loc(asString("int"))))
-  matches `int&`.
+
+
+The matcher referenceTypeLoc(hasReferentLoc(loc(asString("int"))))
+  matches int&.
 </pre></td></tr>
 
 
@@ -9787,10 +12970,14 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   int *a;
-  int const *b;
-  float const *f;
-pointerType(pointee(isConstQualified(), isInteger()))
-  matches "int const *b"
+  const int *b;
+  int * const c = nullptr;
+  const float *f;
+
+The matcher pointerType(pointee(isConstQualified(), isInteger()))
+matches const int *,
+but does not match int * const
+or const float *.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockPointerType.html">BlockPointerType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberPointerType.html">MemberPointerType</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1PointerType.html">PointerType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ReferenceType.html">ReferenceType</a>>
@@ -9801,11 +12988,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasReturnValue0"><pre>Matches the return value expression of a return statement
 
 Given
-  return a + b;
-hasReturnValue(binaryOperator())
-  matches 'return a + b'
-with binaryOperator()
-  matching 'a + b'
+  int foo(int a, int b) {
+    return a + b;
+  }
+The matcher
+returnStmt(hasReturnValue(binaryOperator().bind("op"))) matches
+return a + b, with binaryOperator() matching
+a + b.
 </pre></td></tr>
 
 
@@ -9814,17 +13003,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 a given matcher. Also matches StmtExprs that have CompoundStmt as children.
 
 Given
-  { {}; 1+2; }
-hasAnySubstatement(compoundStmt())
-  matches '{ {}; 1+2; }'
+void foo() { { {}; 1+2; } }
+The matcher
+compoundStmt(hasAnySubstatement(compoundStmt().bind("compound")))
+{ {}; 1+2; } and { { {}; 1+2; } }
 with compoundStmt()
-  matching '{}'
+matching {} and { {}; 1+2; }.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('alignOfExpr0')"><a name="alignOfExpr0Anchor">alignOfExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="alignOfExpr0"><pre>Same as unaryExprOrTypeTraitExpr, but only matching
 alignof.
+
+Given
+  int align = alignof(int);
+
+
+The matcher alignOfExpr(expr())
+matches alignof(int).
 </pre></td></tr>
 
 
@@ -9832,26 +13029,30 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="forCallable0"><pre>Matches declaration of the function, method, or block the statement
 belongs to.
 
-Given:
-F& operator=(const F& o) {
-  std::copy_if(o.begin(), o.end(), begin(), [](V v) { return v > 0; });
-  return *this;
-}
-returnStmt(forCallable(functionDecl(hasName("operator="))))
-  matches 'return *this'
-  but does not match 'return v > 0'
+Given
+struct F {
+  F& operator=(const F& other) {
+    []() { return 42 == 42; };
+    return *this;
+  }
+};
 
-Given:
--(void) foo {
+The matcher returnStmt(forFunction(hasName("operator=")))
+matches return *this
+but does not match return 42 == 42.
+
+Given
+void foo {
   int x = 1;
   dispatch_sync(queue, ^{ int y = 2; });
 }
-declStmt(forCallable(objcMethodDecl()))
-  matches 'int x = 1'
-  but does not match 'int y = 2'.
-whereas declStmt(forCallable(blockDecl()))
-  matches 'int y = 2'
-  but does not match 'int x = 1'.
+
+The matcher declStmt(forCallable(objcMethodDecl()))
+matches int x = 1
+but does not match int y = 2.
+The matcher declStmt(forCallable(blockDecl()))
+matches int y = 2
+but does not match int x = 1.
 </pre></td></tr>
 
 
@@ -9860,23 +13061,34 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Deprecated. Use forCallable() to correctly handle the situation when
 the declaration is not a function (but a block or an Objective-C method).
-forFunction() not only fails to take non-functions into account but also
-may match the wrong declaration in their presence.
+The matcher forFunction() not only fails to take non-functions
+into account but also may match the wrong declaration in their presence.
 
-Given:
-F& operator=(const F& o) {
-  std::copy_if(o.begin(), o.end(), begin(), [](V v) { return v > 0; });
-  return *this;
-}
-returnStmt(forFunction(hasName("operator=")))
-  matches 'return *this'
-  but does not match 'return v > 0'
+Given
+  struct F {
+    F& operator=(const F& other) {
+      []() { return 42 == 42; };
+      return *this;
+    }
+  };
+
+
+The matcher returnStmt(forFunction(hasName("operator=")))
+matches return *this
+but does not match return 42 == 42.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('sizeOfExpr0')"><a name="sizeOfExpr0Anchor">sizeOfExpr</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="sizeOfExpr0"><pre>Same as unaryExprOrTypeTraitExpr, but only matching
 sizeof.
+
+Given
+  struct S { double x; double y; };
+  int size = sizeof(struct S);
+
+The matcher sizeOfExpr(expr())
+matches sizeof(struct S).
 </pre></td></tr>
 
 
@@ -9890,7 +13102,9 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   int i;
   double j = F(i);
 
-substTemplateTypeParmType(hasReplacementType(type())) matches int
+
+The matcher substTemplateTypeParmType(hasReplacementType(type()))
+matches int.
 </pre></td></tr>
 
 
@@ -9899,11 +13113,18 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 statement. This matcher may produce multiple matches.
 
 Given
-  switch (1) { case 1: case 2: default: switch (2) { case 3: case 4: ; } }
-switchStmt(forEachSwitchCase(caseStmt().bind("c"))).bind("s")
-  matches four times, with "c" binding each of "case 1:", "case 2:",
-"case 3:" and "case 4:", and "s" respectively binding "switch (1)",
-"switch (1)", "switch (2)" and "switch (2)".
+  void foo() {
+    switch (1) { case 1: case 2: default: switch (2) { case 3: case 4: ; } }
+  }
+The matcher
+switchStmt(forEachSwitchCase(caseStmt().bind("c")))
+matches four times, matching
+switch (1) { case 1: case 2: default: switch (2) { case 3:
+case 4: ; } } and
+switch (2) { case 3: case 4: ; }, with
+caseStmt() matching each of case 1:,
+case 2:, case 3:
+and case 4:.
 </pre></td></tr>
 
 
@@ -9911,15 +13132,23 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasCondition4"><pre>Matches the condition expression of an if statement, for loop,
 switch statement or conditional operator.
 
-Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true))))
+Given
+void foo() {
   if (true) {}
+}
+
+The matcher ifStmt(hasCondition(cxxBoolLiteral(equals(true))))
+if (true) {}
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1SwitchStmt.html">SwitchStmt</a>></td><td class="name" onclick="toggle('hasInitStatement1')"><a name="hasInitStatement1Anchor">hasInitStatement</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasInitStatement1"><pre>Matches selection statements with initializer.
 
-Given:
+Given
+ struct vec { int* begin(); int* end(); };
+ int foobar();
+ vec& get_range();
  void foo() {
    if (int i = foobar(); i > 0) {}
    switch (int i = foobar(); i) {}
@@ -9930,18 +13159,23 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
    switch (foobar()) {}
    for (auto& x : get_range()) {}
  }
-ifStmt(hasInitStatement(anything()))
-  matches the if statement in foo but not in bar.
-switchStmt(hasInitStatement(anything()))
-  matches the switch statement in foo but not in bar.
-cxxForRangeStmt(hasInitStatement(anything()))
-  matches the range for statement in foo but not in bar.
+
+The matcher ifStmt(hasInitStatement(anything()))
+  matches the if statement if (int i = foobar(); i > 0) {}
+  in foo but not if (foobar() > 0) {} in bar.
+The matcher switchStmt(hasInitStatement(anything()))
+  matches the switch statement switch (int i = foobar(); i) {}
+  in foo but not switch (foobar()) {} in bar.
+The matcher cxxForRangeStmt(hasInitStatement(anything()))
+  matches the range for statement
+  for (auto& a = get_range(); auto& x : a) {} in foo
+  but not for (auto& x : get_range()) {} in bar.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>></td><td class="name" onclick="toggle('hasDeclaration4')"><a name="hasDeclaration4Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration4"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -9951,17 +13185,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -9976,19 +13218,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TemplateArgumentLoc.html">TemplateArgumentLoc</a>></td><td class="name" onclick="toggle('hasTypeLoc11')"><a name="hasTypeLoc11Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc11"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -10008,10 +13257,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   struct B { int next; };
   template<int(B::*next_ptr)> struct A {};
   A<&B::next> a;
+
+The matcher
 templateSpecializationType(hasAnyTemplateArgument(
-  isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next"))))))))
-  matches the specialization A<&B::next> with fieldDecl(...) matching
-    B::next
+  isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next")).bind("next")))))))
+matches the specialization A<&struct B::next>
+with fieldDecl(hasName("next")) matching
+B::next.
 </pre></td></tr>
 
 
@@ -10023,10 +13275,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   struct B { int next; };
   template<int(B::*next_ptr)> struct A {};
   A<&B::next> a;
+
+The matcher
 classTemplateSpecializationDecl(hasAnyTemplateArgument(
-    refersToDeclaration(fieldDecl(hasName("next")))))
-  matches the specialization A<&B::next> with fieldDecl(...) matching
-    B::next
+    refersToDeclaration(fieldDecl(hasName("next")).bind("next"))))
+matches the specialization struct A<&B::next>
+with fieldDecl(hasName("next")) matching
+B::next.
 </pre></td></tr>
 
 
@@ -10036,9 +13291,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   template<int T> struct C {};
   C<42> c;
-classTemplateSpecializationDecl(
+
+The matcher classTemplateSpecializationDecl(
   hasAnyTemplateArgument(refersToIntegralType(asString("int"))))
-  matches the implicit instantiation of C in C<42>.
+matches the implicitly declared specialization
+struct C<42> from the instantiation for the type of the
+variable c .
 </pre></td></tr>
 
 
@@ -10049,9 +13307,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<template <typename> class S> class X {};
   template<typename T> class Y {};
   X<Y> xi;
+
+The matcher
 classTemplateSpecializationDecl(hasAnyTemplateArgument(
-    refersToTemplate(templateName())))
-  matches the specialization X<Y>
+              refersToTemplate(templateName())))
+matches the specialization class X<Y>
 </pre></td></tr>
 
 
@@ -10062,9 +13322,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   struct X {};
   template<typename T> struct A {};
   A<X> a;
+
+The matcher
 classTemplateSpecializationDecl(hasAnyTemplateArgument(refersToType(
-  recordType(hasDeclaration(recordDecl(hasName("X")))))))
-matches the specialization of struct A generated by A<X>.
+            recordType(hasDeclaration(recordDecl(hasName("X")))))))
+matches the specialization struct A<struct X>.
 </pre></td></tr>
 
 
@@ -10077,9 +13339,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   template<typename T> class A {};
   A<int> a;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
-  hasTypeLoc(loc(asString("int")))))))
-  matches `A<int> a`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
+hasTypeLoc(loc(asString("int"))))))))) matches A<int> a.
 </pre></td></tr>
 
 
@@ -10092,9 +13356,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<typename T, typename U> class A {};
   A<double, int> b;
   A<int, double> c;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
-  hasTypeLoc(loc(asString("double")))))))
-  matches `A<double, int> b`, but not `A<int, double> c`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
+hasTypeLoc(loc(asString("double")))))))))
+matches A<double, int> b, but not double> c}.
 </pre></td></tr>
 
 
@@ -10114,13 +13381,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template <typename T, typename U>
   void f(T&& t, U&& u) {}
 
-  bool B = false;
-  f(R, B);
-templateSpecializationType(forEachTemplateArgument(isExpr(expr())))
-  matches twice, with expr() matching 'R * 2' and 'R * 4'
-functionDecl(forEachTemplateArgument(refersToType(builtinType())))
-  matches the specialization f<unsigned, bool> twice, for 'unsigned'
-  and 'bool'
+  void foo() {
+    bool B = false;
+    f(R, B);
+  }
+
+The matcher
+templateSpecializationType(forEachTemplateArgument(isExpr(expr().bind("t_arg"))))
+matches Matrix<int, R * 2, R * 4> twice, with
+expr() matching R * 2 and
+R * 4.
+The matcher
+functionDecl(forEachTemplateArgument(refersToType(qualType().bind("type"))))
+matches the specialization of f twice,
+with qualType() matching
+unsigned and
+bool.
 </pre></td></tr>
 
 
@@ -10134,21 +13410,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<> class A<double> {};
   A<int> a;
 
-  template<typename T> f() {};
+  template<typename T> void f() {};
   void func() { f<int>(); };
 
-classTemplateSpecializationDecl(hasAnyTemplateArgument(
-    refersToType(asString("int"))))
-  matches the specialization A<int>
 
-functionDecl(hasAnyTemplateArgument(refersToType(asString("int"))))
-  matches the specialization f<int>
+The matcher classTemplateSpecializationDecl(
+                        hasAnyTemplateArgument(
+                          refersToType(asString("int"))))
+matches class A<int>.
+
+The matcher
+functionDecl(hasAnyTemplateArgument(
+              refersToType(asString("int"))))
+matches the instantiation of f.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>></td><td class="name" onclick="toggle('hasDeclaration3')"><a name="hasDeclaration3Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration3"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -10158,17 +13438,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -10187,23 +13475,26 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   template<typename T, typename U> class A {};
-  A<bool, int> b;
-  A<int, bool> c;
+  A<double, int> b;
+  A<int, double> c;
 
   template<typename T> void f() {}
   void func() { f<int>(); };
+
+The matcher
 classTemplateSpecializationDecl(hasTemplateArgument(
     1, refersToType(asString("int"))))
-  matches the specialization A<bool, int>
+matches the specialization class A<double, int>.
 
-functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
-  matches the specialization f<int>
+The matcher functionDecl(hasTemplateArgument(0,
+                        refersToType(asString("int"))))
+matches the specialization of f.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>></td><td class="name" onclick="toggle('hasDeclaration2')"><a name="hasDeclaration2Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration2"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -10213,17 +13504,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -10238,25 +13537,37 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td><td class="name" onclick="toggle('loc0')"><a name="loc0Anchor">loc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="loc0"><pre>Matches TypeLocs for which the given inner
 QualType-matcher matches.
+
+  int a = 10;
+
+The matcher typeLoc(loc(qualType(isInteger())))
+matches the int of a .
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypedefNameDecl.html">TypedefNameDecl</a>></td><td class="name" onclick="toggle('hasTypeLoc12')"><a name="hasTypeLoc12Anchor">hasTypeLoc</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> Inner</td></tr>
 <tr><td colspan="4" class="doc" id="hasTypeLoc12"><pre>Matches if the type location of a node matches the inner matcher.
 
-Examples:
+Given
   int x;
-declaratorDecl(hasTypeLoc(loc(asString("int"))))
-  matches int x
+The matcher declaratorDecl(hasTypeLoc(loc(asString("int"))))
+matches int x.
+
+Given
+struct point { point(double, double); };
+point p = point(1.0, -1.0);
 
-auto x = int(3);
-cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-  matches int(3)
+The matcher
+cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))
+matches point(1.0, -1.0).
 
+Given
 struct Foo { Foo(int, int); };
-auto x = Foo(1, 2);
-cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-  matches Foo(1, 2)
+Foo x = Foo(1, 2);
+
+The matcher cxxTemporaryObjectExpr(hasTypeLoc(
+                          loc(asString("Foo"))))
+matches Foo(1, 2).
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXFunctionalCastExpr.html">CXXFunctionalCastExpr</a>>,
@@ -10273,23 +13584,31 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasType2"><pre>Matches if the expression's or declaration's type matches a type
 matcher.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and U (matcher = typedefDecl(hasType(asString("int")))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              asString("class X")))
+Exmaple
  class X {};
  void y(X &x) { x; X z; }
  typedef int U;
  class Y { friend class X; };
  class Z : public virtual X {};
+
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z
+The matcher typedefDecl(hasType(asString("int")))
+matches typedef int U
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>></td><td class="name" onclick="toggle('hasDeclaration1')"><a name="hasDeclaration1Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration1"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -10299,17 +13618,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -10328,8 +13655,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 For example, in:
   class A {};
   using B = A;
-The matcher type(hasUnqualifiedDesugaredType(recordType())) matches
-both B and A.
+  B b;
+
+The matcher
+varDecl(hasType(hasUnqualifiedDesugaredType(recordType())))
+matches B b.
 </pre></td></tr>
 
 
@@ -10338,17 +13668,23 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   int a, c; float b; int s = sizeof(a) + sizeof(b) + alignof(c);
-unaryExprOrTypeTraitExpr(hasArgumentOfType(asString("int"))
-  matches sizeof(a) and alignof(c)
+
+The matcher
+unaryExprOrTypeTraitExpr(hasArgumentOfType(asString("int")))
+matches sizeof(a) and alignof(c)
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UnaryOperator.html">UnaryOperator</a>></td><td class="name" onclick="toggle('hasUnaryOperand0')"><a name="hasUnaryOperand0Anchor">hasUnaryOperand</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasUnaryOperand0"><pre>Matches if the operand of a unary operator matches.
 
-Example matches true (matcher = hasUnaryOperand(
-                                  cxxBoolLiteral(equals(true))))
-  !true
+void foo() {
+  !true;
+}
+
+The matcher
+unaryOperator(hasUnaryOperand(cxxBoolLiteral(equals(true))))
+matches !true.
 </pre></td></tr>
 
 
@@ -10362,17 +13698,20 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
     int m;
     int f(X x) { x.m; return m; }
   };
+
+
+The matcher
 memberExpr(hasObjectExpression(hasType(cxxRecordDecl(hasName("X")))))
-  matches `x.m`, but not `m`; however,
-memberExpr(hasObjectExpression(hasType(pointsTo(
-     cxxRecordDecl(hasName("X"))))))
-  matches `m` (aka. `this->m`), but not `x.m`.
+matches x.m, but not m; however,
+The matcher memberExpr(hasObjectExpression(hasType(pointsTo(
+cxxRecordDecl(hasName("X"))))))
+matches m (aka. this->m), but not x.m.
 </pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>></td><td class="name" onclick="toggle('hasDeclaration0')"><a name="hasDeclaration0Anchor">hasDeclaration</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration0"><pre>Matches a node if the declaration associated with that node
-matches the given matcher.
+  matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
@@ -10382,17 +13721,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 - for CXXNewExpr, the declaration of the operator new
 - for ObjCIvarExpr, the declaration of the ivar
 
-For type nodes, hasDeclaration will generally match the declaration of the
-sugared type. Given
+Given
   class X {};
   typedef X Y;
   Y y;
-in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-typedefDecl. A common use case is to match the underlying, desugared type.
+
+For type nodes, hasDeclaration will generally match the declaration of the
+sugared type, i.e., the matcher
+varDecl(hasType(qualType(hasDeclaration(decl().bind("d"))))),
+matches Y y, with
+the matcher decl() matching
+typedef X Y;.
+A common use case is to match the underlying, desugared type.
 This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-  varDecl(hasType(hasUnqualifiedDesugaredType(
-      recordType(hasDeclaration(decl())))))
-In this matcher, the decl will match the CXXRecordDecl of class X.
+varDecl(hasType(hasUnqualifiedDesugaredType(
+      recordType(hasDeclaration(decl().bind("d"))))))
+matches Y y.
+In this matcher, the matcher decl() will match the
+CXXRecordDecl
+class X {};.
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>,
   Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>,
@@ -10412,8 +13759,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   namespace X { int a; void b(); }
   using X::a;
   using X::b;
+
+The matcher
 usingDecl(hasAnyUsingShadowDecl(hasTargetDecl(functionDecl())))
-  matches using X::b but not using X::a </pre></td></tr>
+  matches using X::b
+  but not X::a}
+</pre></td></tr>
 
 
 <tr><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UsingType.html">UsingType</a>></td><td class="name" onclick="toggle('hasUnderlyingType1')"><a name="hasUnderlyingType1Anchor">hasUnderlyingType</a></td><td>Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr>
@@ -10422,8 +13773,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   decltype(1) a = 1;
   decltype(2.0) b = 2.0;
-decltypeType(hasUnderlyingType(isInteger()))
-  matches the type of "a"
+
+
+The matcher decltypeType(hasUnderlyingType(isInteger()))
+matches the type decltype(1) of the variable
+declaration of a .
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DecltypeType.html">DecltypeType</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UsingType.html">UsingType</a>>
 </pre></td></tr>
@@ -10433,18 +13787,20 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="throughUsingDecl1"><pre>Matches if a node refers to a declaration through a specific
 using shadow declaration.
 
-Examples:
+Given
   namespace a { int f(); }
   using a::f;
   int x = f();
-declRefExpr(throughUsingDecl(anything()))
-  matches f
+
+The matcher declRefExpr(throughUsingDecl(anything()))
+matches f
 
   namespace a { class X{}; }
   using a::X;
   X x;
-typeLoc(loc(usingType(throughUsingDecl(anything()))))
-  matches X
+
+The matcher typeLoc(loc(usingType(throughUsingDecl(anything()))))
+matches X
 
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1UsingType.html">UsingType</a>>
 </pre></td></tr>
@@ -10460,21 +13816,31 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 X, while varDecl(hasType(cxxRecordDecl(hasName("X")))) matches the
 declaration of x.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              cxxRecordDecl(hasName("X"))))
  class X {};
  void y(X &x) { x; X z; }
  class Y { friend class X; };
  class Z : public virtual X {};
 
-Example matches class Derived
-(matcher = cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base"))))))
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z.
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X.
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches
+class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
+
+Given
 class Base {};
 class Derived : Base {};
 
+The matcher
+cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base")))))
+matches class Derived : Base {}.
+
 Usable as: Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1FriendDecl.html">FriendDecl</a>>, Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>>,
 Matcher<<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>>
 </pre></td></tr>
@@ -10484,17 +13850,25 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasType3"><pre>Matches if the expression's or declaration's type matches a type
 matcher.
 
-Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-            and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-            and U (matcher = typedefDecl(hasType(asString("int")))
-            and friend class X (matcher = friendDecl(hasType("X"))
-            and public virtual X (matcher = cxxBaseSpecifier(hasType(
-                                              asString("class X")))
+Exmaple
  class X {};
  void y(X &x) { x; X z; }
  typedef int U;
  class Y { friend class X; };
  class Z : public virtual X {};
+
+The matcher expr(hasType(cxxRecordDecl(hasName("X"))))
+matches x and z.
+The matcher varDecl(hasType(cxxRecordDecl(hasName("X"))))
+matches z
+The matcher typedefDecl(hasType(asString("int")))
+matches typedef int U
+The matcher friendDecl(hasType(asString("class X")))
+matches friend class X
+The matcher cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+asString("X"))).bind("b"))) matches class Z : public virtual X {},
+with cxxBaseSpecifier(...)
+matching public virtual X.
 </pre></td></tr>
 
 
@@ -10502,9 +13876,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasInitializer0"><pre>Matches a variable declaration that has an initializer expression
 that matches the given matcher.
 
-Example matches x (matcher = varDecl(hasInitializer(callExpr())))
-  bool y() { return true; }
-  bool x = y();
+Given
+  int y() { return 0; }
+  void foo() {
+    int x = y();
+  }
+The matcher varDecl(hasInitializer(callExpr()))
+matches x
 </pre></td></tr>
 
 
@@ -10524,13 +13902,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template <typename T, typename U>
   void f(T&& t, U&& u) {}
 
-  bool B = false;
-  f(R, B);
-templateSpecializationType(forEachTemplateArgument(isExpr(expr())))
-  matches twice, with expr() matching 'R * 2' and 'R * 4'
-functionDecl(forEachTemplateArgument(refersToType(builtinType())))
-  matches the specialization f<unsigned, bool> twice, for 'unsigned'
-  and 'bool'
+  void foo() {
+    bool B = false;
+    f(R, B);
+  }
+
+The matcher
+templateSpecializationType(forEachTemplateArgument(isExpr(expr().bind("t_arg"))))
+matches Matrix<int, R * 2, R * 4> twice, with
+expr() matching R * 2 and
+R * 4.
+The matcher
+functionDecl(forEachTemplateArgument(refersToType(qualType().bind("type"))))
+matches the specialization of f twice,
+with qualType() matching
+unsigned and
+bool.
 </pre></td></tr>
 
 
@@ -10543,9 +13930,11 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 Given
   template<typename T> class A {};
   A<int> a;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
-  hasTypeLoc(loc(asString("int")))))))
-  matches `A<int> a`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
+hasTypeLoc(loc(asString("int"))))))))) matches A<int> a.
 </pre></td></tr>
 
 
@@ -10559,15 +13948,19 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<> class A<double> {};
   A<int> a;
 
-  template<typename T> f() {};
+  template<typename T> void f() {};
   void func() { f<int>(); };
 
-classTemplateSpecializationDecl(hasAnyTemplateArgument(
-    refersToType(asString("int"))))
-  matches the specialization A<int>
 
-functionDecl(hasAnyTemplateArgument(refersToType(asString("int"))))
-  matches the specialization f<int>
+The matcher classTemplateSpecializationDecl(
+                        hasAnyTemplateArgument(
+                          refersToType(asString("int"))))
+matches class A<int>.
+
+The matcher
+functionDecl(hasAnyTemplateArgument(
+              refersToType(asString("int"))))
+matches the instantiation of f.
 </pre></td></tr>
 
 
@@ -10580,9 +13973,12 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   template<typename T, typename U> class A {};
   A<double, int> b;
   A<int, double> c;
-varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
-  hasTypeLoc(loc(asString("double")))))))
-  matches `A<double, int> b`, but not `A<int, double> c`.
+
+The matcher
+varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
+hasTypeLoc(loc(asString("double")))))))))
+matches A<double, int> b, but not double> c}.
 </pre></td></tr>
 
 
@@ -10593,17 +13989,20 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 
 Given
   template<typename T, typename U> class A {};
-  A<bool, int> b;
-  A<int, bool> c;
+  A<double, int> b;
+  A<int, double> c;
 
   template<typename T> void f() {}
   void func() { f<int>(); };
+
+The matcher
 classTemplateSpecializationDecl(hasTemplateArgument(
     1, refersToType(asString("int"))))
-  matches the specialization A<bool, int>
+matches the specialization class A<double, int>.
 
-functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
-  matches the specialization f<int>
+The matcher functionDecl(hasTemplateArgument(0,
+                        refersToType(asString("int"))))
+matches the specialization of f.
 </pre></td></tr>
 
 
@@ -10615,9 +14014,10 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
   void f(int b) {
     int a[b];
   }
+The matcher
 variableArrayType(hasSizeExpr(ignoringImpCasts(declRefExpr(to(
   varDecl(hasName("b")))))))
-  matches "int a[b]"
+matches int[b]
 </pre></td></tr>
 
 
@@ -10628,20 +14028,22 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 other declarations of the same function or coroutine.
 
 Given
+void foo() {
   for (;;) {}
-forStmt(hasBody(compoundStmt()))
-  matches 'for (;;) {}'
+}
+The matcher forStmt(hasBody(compoundStmt().bind("body")))
+matches for (;;) {}
 with compoundStmt()
-  matching '{}'
+  matching {}
 
 Given
   void f();
   void f() {}
-functionDecl(hasBody(compoundStmt()))
-  matches 'void f() {}'
+The matcher functionDecl(hasBody(compoundStmt().bind("compound")))
+f
 with compoundStmt()
-  matching '{}'
-  but does not match 'void f();'
+matching {}
+but does not match void f();
 </pre></td></tr>
 
 
@@ -10649,8 +14051,13 @@ <h2 id="traversal-matchers">AST Traversal Matchers</h2>
 <tr><td colspan="4" class="doc" id="hasCondition2"><pre>Matches the condition expression of an if statement, for loop,
 switch statement or conditional operator.
 
-Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true))))
+Given
+void foo() {
   if (true) {}
+}
+
+The matcher ifStmt(hasCondition(cxxBoolLiteral(equals(true))))
+if (true) {}
 </pre></td></tr>
 
 <!--END_TRAVERSAL_MATCHERS -->
diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 32515fbac64f6..b8f17b1944238 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -980,6 +980,8 @@ AST Matchers
 - Fixed ``forEachArgumentWithParam`` and ``forEachArgumentWithParamType`` to
   not skip the explicit object parameter for operator calls.
 - Fixed captureVars assertion failure if not capturesVariables. (#GH76425)
+- The examples in the AST matcher reference are now tested and additional
+  examples and descriptions were added.
 
 clang-format
 ------------
diff --git a/clang/docs/doxygen.cfg.in b/clang/docs/doxygen.cfg.in
index 251afb179b205..1d1deb0fcfb07 100644
--- a/clang/docs/doxygen.cfg.in
+++ b/clang/docs/doxygen.cfg.in
@@ -220,7 +220,14 @@ TAB_SIZE               = 2
 # "Side Effects:". You can put \n's in the value part of an alias to insert
 # newlines.
 
-ALIASES                =
+ALIASES                += compile_args{1}="Compiled with <tt>\1</tt>.\n"
+ALIASES                += matcher{1}="<tt>\1</tt>"
+ALIASES                += matcher{2$}="<tt>\2</tt>"
+ALIASES                += match{1}="<tt>\1</tt>"
+ALIASES                += match{2$}="<tt>\2</tt>"
+ALIASES                += nomatch{1}="<tt>\1</tt>"
+ALIASES                += header{1}="\code"
+ALIASES                += endheader="\endcode"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
diff --git a/clang/docs/tools/dump_ast_matchers.py b/clang/docs/tools/dump_ast_matchers.py
index 705ff0d4d4098..a3feac8728c65 100755
--- a/clang/docs/tools/dump_ast_matchers.py
+++ b/clang/docs/tools/dump_ast_matchers.py
@@ -100,15 +100,72 @@ def extract_result_types(comment):
         comment = m.group(1)
 
 
+def find_next_closing_rbrace(
+    data: str, start_pos: int, braces_to_be_matched: int
+) -> int:
+    """Finds the location of the closing rbrace '}' inside of data."""
+    """'start_pos' should be one past the opening lbrace and braces_to_be_matched is initialized with 0"""
+    next_lbrace = data.find("{", start_pos)
+    next_rbrace = data.find("}", start_pos)
+    if next_lbrace != -1:
+        if next_lbrace < next_rbrace:
+            return find_next_closing_rbrace(
+                data, next_lbrace + 1, braces_to_be_matched + 1
+            )
+        if braces_to_be_matched == 0:
+            return next_rbrace
+        return find_next_closing_rbrace(data, next_rbrace + 1, braces_to_be_matched - 1)
+
+    if braces_to_be_matched > 0:
+        return find_next_closing_rbrace(data, next_rbrace + 1, braces_to_be_matched - 1)
+
+    return next_rbrace
+
+
 def strip_doxygen(comment):
     """Returns the given comment without \-escaped words."""
-    # If there is only a doxygen keyword in the line, delete the whole line.
-    comment = re.sub(r"^\\[^\s]+\n", r"", comment, flags=re.M)
-
     # If there is a doxygen \see command, change the \see prefix into "See also:".
     # FIXME: it would be better to turn this into a link to the target instead.
     comment = re.sub(r"\\see", r"See also:", comment)
 
+    commands: list[str] = [
+        "\\compile_args{",
+        "\\matcher{",
+        "\\match{",
+        "\\nomatch{",
+    ]
+
+    for command in commands:
+        delete_command = command == "\\compile_args{"
+        command_begin_loc = comment.find(command)
+        while command_begin_loc != -1:
+            command_end_loc = command_begin_loc + len(command)
+            end_brace_loc = find_next_closing_rbrace(comment, command_end_loc + 1, 0)
+            if end_brace_loc == -1:
+                print("found unmatched {")
+                command_begin_loc = comment.find(command, command_end_loc)
+                continue
+
+            if delete_command:
+                comment = comment[0:command_begin_loc] + comment[end_brace_loc + 1 :]
+                command_begin_loc = comment.find(command, command_begin_loc)
+                continue
+
+            tag_seperator_loc = comment.find("$", command_end_loc)
+            if tag_seperator_loc != -1 and tag_seperator_loc < end_brace_loc:
+                command_end_loc = tag_seperator_loc + 1
+
+            comment = (
+                comment[0:command_begin_loc]
+                + comment[command_end_loc:end_brace_loc]
+                + comment[end_brace_loc + 1 :]
+            )
+
+            command_begin_loc = comment.find(command, command_begin_loc)
+
+    # If there is only a doxygen keyword in the line, delete the whole line.
+    comment = re.sub(r"^\\[^\s]+\n", r"", comment, flags=re.M)
+
     # Delete the doxygen command and the following whitespace.
     comment = re.sub(r"\\[^\s]+\s+", r"", comment)
     return comment
@@ -191,8 +248,9 @@ def act_on_decl(declaration, comment, allowed_types):
     definition.
     """
     if declaration.strip():
-
-        if re.match(r"^\s?(#|namespace|using|template <typename NodeType> using|})", declaration):
+        if re.match(
+            r"^\s?(#|namespace|using|template <typename NodeType> using|})", declaration
+        ):
             return
 
         # Node matchers are defined by writing:
diff --git a/clang/include/clang/ASTMatchers/ASTMatchers.h b/clang/include/clang/ASTMatchers/ASTMatchers.h
index 0f3257db6f415..8b5849030ee15 100644
--- a/clang/include/clang/ASTMatchers/ASTMatchers.h
+++ b/clang/include/clang/ASTMatchers/ASTMatchers.h
@@ -160,13 +160,13 @@ using AttrMatcher = internal::Matcher<Attr>;
 /// additional constraint. This will often be used with an explicit conversion
 /// to an \c internal::Matcher<> type such as \c TypeMatcher.
 ///
-/// Example: \c DeclarationMatcher(anything()) matches all declarations, e.g.,
+/// Given
 /// \code
-/// "int* p" and "void f()" in
 ///   int* p;
 ///   void f();
 /// \endcode
-///
+/// The matcher \matcher{decl(anything())}
+/// matches \match{int* p} and \match{void f()}.
 /// Usable as: Any Matcher
 inline internal::TrueMatcher anything() { return internal::TrueMatcher(); }
 
@@ -176,11 +176,13 @@ inline internal::TrueMatcher anything() { return internal::TrueMatcher(); }
 /// \code
 ///   int X;
 ///   namespace NS {
-///   int Y;
+///     int Y;
 ///   }  // namespace NS
 /// \endcode
-/// decl(hasDeclContext(translationUnitDecl()))
-///   matches "int X", but not "int Y".
+/// \compile_args{-std=c++}
+/// The matcher \matcher{namedDecl(hasDeclContext(translationUnitDecl()))}
+/// matches \match{type=name$X} and \match{type=name$NS},
+/// but does not match \nomatch{type=name$Y}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, TranslationUnitDecl>
     translationUnitDecl;
 
@@ -191,8 +193,10 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, TranslationUnitDecl>
 ///   typedef int X;
 ///   using Y = int;
 /// \endcode
-/// typedefDecl()
-///   matches "typedef int X", but not "using Y = int"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{typedefDecl()}
+/// matches \match{typedef int X},
+/// but does not match \nomatch{using Y = int}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, TypedefDecl>
     typedefDecl;
 
@@ -203,8 +207,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, TypedefDecl>
 ///   typedef int X;
 ///   using Y = int;
 /// \endcode
-/// typedefNameDecl()
-///   matches "typedef int X" and "using Y = int"
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{typedefNameDecl()}
+/// matches \match{typedef int X} and \match{using Y = int}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, TypedefNameDecl>
     typedefNameDecl;
 
@@ -215,34 +220,45 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, TypedefNameDecl>
 ///   typedef int X;
 ///   using Y = int;
 /// \endcode
-/// typeAliasDecl()
-///   matches "using Y = int", but not "typedef int X"
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{typeAliasDecl()}
+/// matches \match{using Y = int},
+/// but does not match \nomatch{typedef int X}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, TypeAliasDecl>
     typeAliasDecl;
 
 /// Matches type alias template declarations.
 ///
-/// typeAliasTemplateDecl() matches
+/// Given
 /// \code
-///   template <typename T>
-///   using Y = X<T>;
+///   template <typename T> struct X {};
+///   template <typename T> using Y = X<T>;
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{typeAliasTemplateDecl()}
+/// matches \match{template <typename T> using Y = X<T>}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, TypeAliasTemplateDecl>
     typeAliasTemplateDecl;
 
 /// Matches AST nodes that were expanded within the main-file.
 ///
-/// Example matches X but not Y
-///   (matcher = cxxRecordDecl(isExpansionInMainFile())
+/// Given the header \c Y.h
+/// \header{Y.h}
+///   #pragma once
+///   typedef int my_header_int;
+/// \endheader
+/// and the source file
 /// \code
-///   #include <Y.h>
-///   class X {};
-/// \endcode
-/// Y.h:
-/// \code
-///   class Y {};
+///   #include "Y.h"
+///   typedef int my_main_file_int;
+///   my_main_file_int a = 0;
+///   my_header_int b = 1;
 /// \endcode
 ///
+/// The matcher \matcher{typedefDecl(isExpansionInMainFile())}
+/// matches \match{typedef int my_main_file_int},
+/// but does not match \nomatch{typedef int my_header_int}.
+///
 /// Usable as: Matcher<Decl>, Matcher<Stmt>, Matcher<TypeLoc>
 AST_POLYMORPHIC_MATCHER(isExpansionInMainFile,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(Decl, Stmt, TypeLoc)) {
@@ -253,16 +269,21 @@ AST_POLYMORPHIC_MATCHER(isExpansionInMainFile,
 
 /// Matches AST nodes that were expanded within system-header-files.
 ///
-/// Example matches Y but not X
-///     (matcher = cxxRecordDecl(isExpansionInSystemHeader())
+/// Given the header \c SystemHeader.h
+/// \header{system_include/SystemHeader.h}
+///   #pragma once
+///   int header();
+/// \endheader
+/// and the source code
 /// \code
 ///   #include <SystemHeader.h>
-///   class X {};
-/// \endcode
-/// SystemHeader.h:
-/// \code
-///   class Y {};
+///   static int main_file();
 /// \endcode
+/// \compile_args{-isystemsystem_include/}
+///
+/// The matcher \matcher{type=none$functionDecl(isExpansionInSystemHeader())}
+/// matches \match{int header()},
+/// but does not match \nomatch{static int main_file()}.
 ///
 /// Usable as: Matcher<Decl>, Matcher<Stmt>, Matcher<TypeLoc>
 AST_POLYMORPHIC_MATCHER(isExpansionInSystemHeader,
@@ -278,17 +299,32 @@ AST_POLYMORPHIC_MATCHER(isExpansionInSystemHeader,
 /// Matches AST nodes that were expanded within files whose name is
 /// partially matching a given regex.
 ///
-/// Example matches Y but not X
-///     (matcher = cxxRecordDecl(isExpansionInFileMatching("AST.*"))
-/// \code
-///   #include "ASTMatcher.h"
-///   class X {};
-/// \endcode
-/// ASTMatcher.h:
-/// \code
-///   class Y {};
+/// Given the headers \c Y.h
+/// \header{Y.h}
+///   #pragma once
+///   typedef int my_y_int;
+/// \endheader
+/// and \c X.h
+/// \header{X.h}
+///   #pragma once
+///   typedef int my_x_int;
+/// \endheader
+/// and the source code
+/// \code
+///   #include "X.h"
+///   #include "Y.h"
+///   typedef int my_main_file_int;
+///   my_main_file_int a = 0;
+///   my_x_int b = 1;
+///   my_y_int c = 2;
 /// \endcode
 ///
+/// The matcher
+/// \matcher{type=none$typedefDecl(isExpansionInFileMatching("Y.h"))}
+/// matches \match{typedef int my_y_int},
+/// but does not match \nomatch{typedef int my_main_file_int} or
+/// \nomatch{typedef int my_x_int}.
+///
 /// Usable as: Matcher<Decl>, Matcher<Stmt>, Matcher<TypeLoc>
 AST_POLYMORPHIC_MATCHER_REGEX(isExpansionInFileMatching,
                               AST_POLYMORPHIC_SUPPORTED_TYPES(Decl, Stmt,
@@ -313,6 +349,17 @@ AST_POLYMORPHIC_MATCHER_REGEX(isExpansionInFileMatching,
 /// Does not match if only part of the statement is expanded from that macro or
 /// if different parts of the statement are expanded from different
 /// appearances of the macro.
+///
+/// Given
+/// \code
+///   #define A 0
+///   #define B A
+///   int c = B;
+/// \endcode
+///
+/// The matcher \matcher{integerLiteral(isExpandedFromMacro("A"))}
+/// matches the literal expanded at the initializer \match{B} of the variable
+/// \c c .
 AST_POLYMORPHIC_MATCHER_P(isExpandedFromMacro,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(Decl, Stmt, TypeLoc),
                           std::string, MacroName) {
@@ -330,35 +377,46 @@ AST_POLYMORPHIC_MATCHER_P(isExpandedFromMacro,
 
 /// Matches declarations.
 ///
-/// Examples matches \c X, \c C, and the friend declaration inside \c C;
+/// Given
 /// \code
 ///   void X();
 ///   class C {
-///     friend X;
+///     friend void X();
 ///   };
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{decl()}
+/// matches \match{void X()}, \match{type=name;count=2$C}
+/// and \match{count=2$friend void X()}.
 extern const internal::VariadicAllOfMatcher<Decl> decl;
 
 /// Matches decomposition-declarations.
 ///
-/// Examples matches the declaration node with \c foo and \c bar, but not
-/// \c number.
-/// (matcher = declStmt(has(decompositionDecl())))
-///
+/// Given
 /// \code
+///   struct pair { int x; int y; };
+///   pair make(int, int);
 ///   int number = 42;
-///   auto [foo, bar] = std::make_pair{42, 42};
+///   auto [foo, bar] = make(42, 42);
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+/// The matcher \matcher{decompositionDecl()}
+/// matches \match{auto [foo, bar] = make(42, 42)},
+/// but does not match \nomatch{type=name$number}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, DecompositionDecl>
     decompositionDecl;
 
 /// Matches binding declarations
-/// Example matches \c foo and \c bar
-/// (matcher = bindingDecl()
 ///
+/// Given
 /// \code
-///   auto [foo, bar] = std::make_pair{42, 42};
+///   struct pair { int x; int y; };
+///   pair make(int, int);
+///   auto [foo, bar] = make(42, 42);
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+/// The matcher \matcher{bindingDecl()}
+/// matches \match{type=name;count=2$foo} and \match{type=name;count=2$bar}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, BindingDecl>
     bindingDecl;
 
@@ -368,14 +426,16 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, BindingDecl>
 /// \code
 ///   extern "C" {}
 /// \endcode
-/// linkageSpecDecl()
-///   matches "extern "C" {}"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{linkageSpecDecl()}
+/// matches \match{extern "C" {}}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, LinkageSpecDecl>
     linkageSpecDecl;
 
 /// Matches a declaration of anything that could have a name.
 ///
 /// Example matches \c X, \c S, the anonymous union type, \c i, and \c U;
+/// Given
 /// \code
 ///   typedef int X;
 ///   struct S {
@@ -384,17 +444,25 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, LinkageSpecDecl>
 ///     } U;
 ///   };
 /// \endcode
+/// The matcher \matcher{namedDecl()}
+/// matches \match{typedef int X}, \match{type=name;std=c$S}, \match{int i}
+/// \match{type=name$} and \match{type=name$U},
+/// with \match{type=name;count=2;std=c++$S} matching twice in C++.
+/// Once for the injected class name and once for the declaration itself.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, NamedDecl> namedDecl;
 
 /// Matches a declaration of label.
 ///
 /// Given
 /// \code
-///   goto FOO;
-///   FOO: bar();
+///   void bar();
+///   void foo() {
+///     goto FOO;
+///     FOO: bar();
+///   }
 /// \endcode
-/// labelDecl()
-///   matches 'FOO:'
+/// The matcher \matcher{type=none$labelDecl()}
+/// matches \match{FOO: bar()}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, LabelDecl> labelDecl;
 
 /// Matches a declaration of a namespace.
@@ -404,8 +472,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, LabelDecl> labelDecl;
 ///   namespace {}
 ///   namespace test {}
 /// \endcode
-/// namespaceDecl()
-///   matches "namespace {}" and "namespace test {}"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{namespaceDecl()}
+/// matches \match{namespace {}} and \match{namespace test {}}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, NamespaceDecl>
     namespaceDecl;
 
@@ -416,38 +485,50 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, NamespaceDecl>
 ///   namespace test {}
 ///   namespace alias = ::test;
 /// \endcode
-/// namespaceAliasDecl()
-///   matches "namespace alias" but not "namespace test"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{namespaceAliasDecl()}
+/// matches \match{type=name$alias},
+/// but does not match \nomatch{type=name$test}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, NamespaceAliasDecl>
     namespaceAliasDecl;
 
 /// Matches class, struct, and union declarations.
 ///
-/// Example matches \c X, \c Z, \c U, and \c S
+/// Given
 /// \code
 ///   class X;
 ///   template<class T> class Z {};
 ///   struct S {};
 ///   union U {};
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{recordDecl()}
+/// matches \match{type=name$X}, \match{type=name;count=2$Z},
+/// \match{type=name;count=2$S} and \match{type=name;count=2$U}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, RecordDecl> recordDecl;
 
 /// Matches C++ class declarations.
 ///
-/// Example matches \c X, \c Z
+/// Given
 /// \code
 ///   class X;
 ///   template<class T> class Z {};
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{cxxRecordDecl()}
+/// matches \match{type=name$X} and \match{type=name;count=2$Z}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, CXXRecordDecl>
     cxxRecordDecl;
 
 /// Matches C++ class template declarations.
 ///
-/// Example matches \c Z
+/// Given
 /// \code
 ///   template<class T> class Z {};
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{classTemplateDecl()}
+/// matches \match{type=name$Z}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ClassTemplateDecl>
     classTemplateDecl;
 
@@ -459,8 +540,10 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ClassTemplateDecl>
 ///   template<> class A<double> {};
 ///   A<int> a;
 /// \endcode
-/// classTemplateSpecializationDecl()
-///   matches the specializations \c A<int> and \c A<double>
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{classTemplateSpecializationDecl()}
+/// matches \match{type=typestr$class A<int>}
+/// and \match{type=typestr$class A<double>}.
 extern const internal::VariadicDynCastAllOfMatcher<
     Decl, ClassTemplateSpecializationDecl>
     classTemplateSpecializationDecl;
@@ -472,14 +555,15 @@ extern const internal::VariadicDynCastAllOfMatcher<
 ///   template<class T1, class T2, int I>
 ///   class A {};
 ///
-///   template<class T, int I>
-///   class A<T, T*, I> {};
+///   template<class T, int I> class A<T, T*, I> {};
 ///
 ///   template<>
 ///   class A<int, int, 1> {};
 /// \endcode
-/// classTemplatePartialSpecializationDecl()
-///   matches the specialization \c A<T,T*,I> but not \c A<int,int,1>
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{classTemplatePartialSpecializationDecl()}
+/// matches \match{template<class T, int I> class A<T, T*, I> {}},
+/// but does not match \nomatch{A<int, int, 1>}.
 extern const internal::VariadicDynCastAllOfMatcher<
     Decl, ClassTemplatePartialSpecializationDecl>
     classTemplatePartialSpecializationDecl;
@@ -491,8 +575,9 @@ extern const internal::VariadicDynCastAllOfMatcher<
 /// \code
 ///   class X { int y; };
 /// \endcode
-/// declaratorDecl()
-///   matches \c int y.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{declaratorDecl()}
+/// matches \match{int y}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, DeclaratorDecl>
     declaratorDecl;
 
@@ -502,8 +587,8 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, DeclaratorDecl>
 /// \code
 ///   void f(int x);
 /// \endcode
-/// parmVarDecl()
-///   matches \c int x.
+/// The matcher \matcher{parmVarDecl()}
+/// matches \match{int x}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ParmVarDecl>
     parmVarDecl;
 
@@ -516,29 +601,36 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ParmVarDecl>
 ///     int a;
 ///   };
 /// \endcode
-/// accessSpecDecl()
-///   matches 'public:'
+/// \compile_args{-std=c++}
+/// The matcher \matcher{accessSpecDecl()}
+/// matches \match{public:}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, AccessSpecDecl>
     accessSpecDecl;
 
 /// Matches class bases.
 ///
-/// Examples matches \c public virtual B.
+/// Given
 /// \code
 ///   class B {};
 ///   class C : public virtual B {};
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(hasDirectBase(cxxBaseSpecifier()))}
+/// matches \match{type=name$C}.
 extern const internal::VariadicAllOfMatcher<CXXBaseSpecifier> cxxBaseSpecifier;
 
 /// Matches constructor initializers.
 ///
-/// Examples matches \c i(42).
+/// Given
 /// \code
 ///   class C {
 ///     C() : i(42) {}
 ///     int i;
 ///   };
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxCtorInitializer()}
+/// matches \match{i(42)}.
 extern const internal::VariadicAllOfMatcher<CXXCtorInitializer>
     cxxCtorInitializer;
 
@@ -549,8 +641,10 @@ extern const internal::VariadicAllOfMatcher<CXXCtorInitializer>
 ///   template <typename T> struct C {};
 ///   C<int> c;
 /// \endcode
-/// templateArgument()
-///   matches 'int' in C<int>.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{templateSpecializationType(hasAnyTemplateArgument(templateArgument()))}
+/// matches \match{type=typestr$C<int>}.
 extern const internal::VariadicAllOfMatcher<TemplateArgument> templateArgument;
 
 /// Matches template arguments (with location info).
@@ -560,8 +654,9 @@ extern const internal::VariadicAllOfMatcher<TemplateArgument> templateArgument;
 ///   template <typename T> struct C {};
 ///   C<int> c;
 /// \endcode
-/// templateArgumentLoc()
-///   matches 'int' in C<int>.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{templateArgumentLoc()}
+/// matches \match{int} in C<int>.
 extern const internal::VariadicAllOfMatcher<TemplateArgumentLoc>
     templateArgumentLoc;
 
@@ -569,11 +664,15 @@ extern const internal::VariadicAllOfMatcher<TemplateArgumentLoc>
 ///
 /// Given
 /// \code
-///   template <typename T> class X { };
-///   X<int> xi;
+///   template<template <typename> class S> class X {};
+///   template<typename T> class Y {};
+///   X<Y> xi;
 /// \endcode
-/// templateName()
-///   matches 'X' in X<int>.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{classTemplateSpecializationDecl(hasAnyTemplateArgument(
+///               refersToTemplate(templateName())))}
+/// matches the specialization \match{type=typestr$class X<Y>}
 extern const internal::VariadicAllOfMatcher<TemplateName> templateName;
 
 /// Matches non-type template parameter declarations.
@@ -582,8 +681,10 @@ extern const internal::VariadicAllOfMatcher<TemplateName> templateName;
 /// \code
 ///   template <typename T, int N> struct C {};
 /// \endcode
-/// nonTypeTemplateParmDecl()
-///   matches 'N', but not 'T'.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{nonTypeTemplateParmDecl()}
+/// matches \match{int N},
+/// but does not match \nomatch{typename T}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl,
                                                    NonTypeTemplateParmDecl>
     nonTypeTemplateParmDecl;
@@ -594,8 +695,10 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl,
 /// \code
 ///   template <typename T, int N> struct C {};
 /// \endcode
-/// templateTypeParmDecl()
-///   matches 'T', but not 'N'.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{templateTypeParmDecl()}
+/// matches \match{typename T},
+/// but does not \nomatch{int N}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, TemplateTypeParmDecl>
     templateTypeParmDecl;
 
@@ -605,8 +708,10 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, TemplateTypeParmDecl>
 /// \code
 ///   template <template <typename> class Z, int N> struct C {};
 /// \endcode
-/// templateTypeParmDecl()
-///   matches 'Z', but not 'N'.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{templateTemplateParmDecl()}
+/// matches \match{template <typename> class Z},
+/// but does not match \nomatch{int N}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl,
                                                    TemplateTemplateParmDecl>
     templateTemplateParmDecl;
@@ -614,20 +719,30 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl,
 /// Matches public C++ declarations and C++ base specifers that specify public
 /// inheritance.
 ///
-/// Examples:
+/// Given
 /// \code
 ///   class C {
-///   public:    int a; // fieldDecl(isPublic()) matches 'a'
+///   public:    int a;
 ///   protected: int b;
 ///   private:   int c;
 ///   };
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{fieldDecl(isPublic())}
+/// matches \match{type=name$a}.
 ///
+/// Given
 /// \code
 ///   class Base {};
-///   class Derived1 : public Base {}; // matches 'Base'
-///   struct Derived2 : Base {}; // matches 'Base'
+///   class Derived1 : public Base {};
+///   struct Derived2 : Base {};
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isPublic()).bind("base")))}
+/// matches \match{type=name$Derived1} and \match{type=name$Derived2},
+/// with \matcher{type=sub$cxxBaseSpecifier(isPublic())} matching
+/// \match{sub=base$public Base} and \match{sub=base$Base}.
 AST_POLYMORPHIC_MATCHER(isPublic,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(Decl,
                                                         CXXBaseSpecifier)) {
@@ -637,19 +752,28 @@ AST_POLYMORPHIC_MATCHER(isPublic,
 /// Matches protected C++ declarations and C++ base specifers that specify
 /// protected inheritance.
 ///
-/// Examples:
+/// Given
 /// \code
 ///   class C {
 ///   public:    int a;
-///   protected: int b; // fieldDecl(isProtected()) matches 'b'
+///   protected: int b;
 ///   private:   int c;
 ///   };
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{fieldDecl(isProtected())}
+/// matches \match{type=name$b}.
 ///
 /// \code
 ///   class Base {};
-///   class Derived : protected Base {}; // matches 'Base'
+///   class Derived : protected Base {};
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isProtected()).bind("base")))}
+/// matches \match{type=name$Derived}, with
+/// \matcher{type=sub$cxxBaseSpecifier(isProtected())} matching
+/// \match{sub=base$Base}.
 AST_POLYMORPHIC_MATCHER(isProtected,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(Decl,
                                                         CXXBaseSpecifier)) {
@@ -659,20 +783,29 @@ AST_POLYMORPHIC_MATCHER(isProtected,
 /// Matches private C++ declarations and C++ base specifers that specify private
 /// inheritance.
 ///
-/// Examples:
+/// Given
 /// \code
 ///   class C {
 ///   public:    int a;
 ///   protected: int b;
-///   private:   int c; // fieldDecl(isPrivate()) matches 'c'
+///   private:   int c;
 ///   };
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{fieldDecl(isPrivate())}
+/// matches \match{type=name$c}.
 ///
 /// \code
 ///   struct Base {};
-///   struct Derived1 : private Base {}; // matches 'Base'
-///   class Derived2 : Base {}; // matches 'Base'
+///   struct Derived1 : private Base {}; // \match{Base}
+///   class Derived2 : Base {}; // \match{Base}
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(isPrivate()).bind("base")))}
+/// matches \match{type=name$Derived1} and \match{type=name$Derived2}, with
+/// \matcher{type=sub$cxxBaseSpecifier(isPrivate())} matching
+/// \match{sub=base;count=2$Base}.
 AST_POLYMORPHIC_MATCHER(isPrivate,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(Decl,
                                                         CXXBaseSpecifier)) {
@@ -688,11 +821,11 @@ AST_POLYMORPHIC_MATCHER(isPrivate,
 ///     int b;
 ///   };
 /// \endcode
-/// fieldDecl(isBitField())
-///   matches 'int a;' but not 'int b;'.
-AST_MATCHER(FieldDecl, isBitField) {
-  return Node.isBitField();
-}
+/// \compile_args{-std=c++}
+/// The matcher \matcher{fieldDecl(isBitField())}
+/// matches \match{type=name$a},
+/// but does not match \nomatch{type=name$b}.
+AST_MATCHER(FieldDecl, isBitField) { return Node.isBitField(); }
 
 /// Matches non-static data members that are bit-fields of the specified
 /// bit width.
@@ -705,8 +838,10 @@ AST_MATCHER(FieldDecl, isBitField) {
 ///     int c : 2;
 ///   };
 /// \endcode
-/// fieldDecl(hasBitWidth(2))
-///   matches 'int a;' and 'int c;' but not 'int b;'.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{fieldDecl(hasBitWidth(2))}
+/// matches \match{type=name$a} and \match{type=name$c},
+/// but not \nomatch{type=name$b}.
 AST_MATCHER_P(FieldDecl, hasBitWidth, unsigned, Width) {
   return Node.isBitField() &&
          Node.getBitWidthValue(Finder->getASTContext()) == Width;
@@ -722,10 +857,14 @@ AST_MATCHER_P(FieldDecl, hasBitWidth, unsigned, Width) {
 ///     int c;
 ///   };
 /// \endcode
-/// fieldDecl(hasInClassInitializer(integerLiteral(equals(2))))
-///   matches 'int a;' but not 'int b;'.
-/// fieldDecl(hasInClassInitializer(anything()))
-///   matches 'int a;' and 'int b;' but not 'int c;'.
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{fieldDecl(hasInClassInitializer(integerLiteral(equals(2))))}
+/// matches \match{type=name$a},
+/// but does not match \nomatch{type=name$b}.
+/// The matcher \matcher{fieldDecl(hasInClassInitializer(anything()))}
+/// matches \match{type=name$a} and \match{type=name$b},
+/// but does not match \nomatch{type=name$c}.
 AST_MATCHER_P(FieldDecl, hasInClassInitializer, internal::Matcher<Expr>,
               InnerMatcher) {
   const Expr *Initializer = Node.getInClassInitializer();
@@ -735,20 +874,29 @@ AST_MATCHER_P(FieldDecl, hasInClassInitializer, internal::Matcher<Expr>,
 
 /// Determines whether the function is "main", which is the entry point
 /// into an executable program.
-AST_MATCHER(FunctionDecl, isMain) {
-  return Node.isMain();
-}
+///
+/// Given
+/// \code
+///   void f();
+///   int main() {}
+/// \endcode
+///
+/// The matcher \matcher{functionDecl(isMain())} matches \match{int main() {}}.
+AST_MATCHER(FunctionDecl, isMain) { return Node.isMain(); }
 
 /// Matches the specialized template of a specialization declaration.
 ///
 /// Given
 /// \code
-///   template<typename T> class A {}; #1
-///   template<> class A<int> {}; #2
+///   template<typename T> class A {}; // #1
+///   template<> class A<int> {}; // #2
 /// \endcode
-/// classTemplateSpecializationDecl(hasSpecializedTemplate(classTemplateDecl()))
-///   matches '#2' with classTemplateDecl() matching the class template
-///   declaration of 'A' at #1.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{classTemplateSpecializationDecl(hasSpecializedTemplate(classTemplateDecl().bind("ctd")))}
+/// matches \match{template<> class A<int> {}},
+/// with \matcher{type=sub$classTemplateDecl()} matching the class template
+/// declaration \match{sub=ctd$template <typename T> class A {}}.
 AST_MATCHER_P(ClassTemplateSpecializationDecl, hasSpecializedTemplate,
               internal::Matcher<ClassTemplateDecl>, InnerMatcher) {
   const ClassTemplateDecl* Decl = Node.getSpecializedTemplate();
@@ -758,6 +906,22 @@ AST_MATCHER_P(ClassTemplateSpecializationDecl, hasSpecializedTemplate,
 
 /// Matches an entity that has been implicitly added by the compiler (e.g.
 /// implicit default/copy constructors).
+///
+/// Given
+/// \code
+///   struct S {};
+///   void f(S obj) {
+///     S copy = obj;
+///     [&](){ return copy; };
+///   }
+/// \endcode
+/// \compile_args{-std=c++11}
+///
+/// The matcher \matcher{cxxConstructorDecl(isImplicit(), isCopyConstructor())}
+/// matches the implicit copy constructor of \match{S}.
+/// The matcher \matcher{lambdaExpr(forEachLambdaCapture(
+///     lambdaCapture(isImplicit())))} matches \match{[&](){ return copy; }},
+/// because it implicitly captures \c copy .
 AST_POLYMORPHIC_MATCHER(isImplicit,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(Decl, Attr,
                                                         LambdaCapture)) {
@@ -774,17 +938,20 @@ AST_POLYMORPHIC_MATCHER(isImplicit,
 ///   template<> class A<double> {};
 ///   A<int> a;
 ///
-///   template<typename T> f() {};
+///   template<typename T> void f() {};
 ///   void func() { f<int>(); };
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
 ///
-/// \endcode
-/// classTemplateSpecializationDecl(hasAnyTemplateArgument(
-///     refersToType(asString("int"))))
-///   matches the specialization \c A<int>
+/// The matcher \matcher{classTemplateSpecializationDecl(
+///                         hasAnyTemplateArgument(
+///                           refersToType(asString("int"))))}
+/// matches \match{type=typestr$class A<int>}.
 ///
-/// functionDecl(hasAnyTemplateArgument(refersToType(asString("int"))))
-///   matches the specialization \c f<int>
+/// The matcher
+/// \matcher{functionDecl(hasAnyTemplateArgument(
+///               refersToType(asString("int"))))}
+/// matches the instantiation of \match{type=name$f}.
 AST_POLYMORPHIC_MATCHER_P(
     hasAnyTemplateArgument,
     AST_POLYMORPHIC_SUPPORTED_TYPES(ClassTemplateSpecializationDecl,
@@ -807,12 +974,10 @@ AST_POLYMORPHIC_MATCHER_P(
 ///   }
 /// \endcode
 /// The matcher
-/// \code
-///   traverse(TK_IgnoreUnlessSpelledInSource,
+/// \matcher{traverse(TK_IgnoreUnlessSpelledInSource,
 ///     varDecl(hasInitializer(floatLiteral().bind("init")))
-///   )
-/// \endcode
-/// matches the variable declaration with "init" bound to the "3.0".
+///   )}
+///   matches \match{int i = 3.0} with "init" bound to \match{sub=init$3.0}.
 template <typename T>
 internal::Matcher<T> traverse(TraversalKind TK,
                               const internal::Matcher<T> &InnerMatcher) {
@@ -873,25 +1038,37 @@ traverse(TraversalKind TK, const internal::MapAnyOfHelper<T...> &InnerMatcher) {
 /// nodes are stripped off.
 ///
 /// Parentheses and explicit casts are not discarded.
+///
 /// Given
 /// \code
-///   class C {};
-///   C a = C();
-///   C b;
-///   C c = b;
-/// \endcode
-/// The matchers
-/// \code
-///    varDecl(hasInitializer(ignoringImplicit(cxxConstructExpr())))
-/// \endcode
-/// would match the declarations for a, b, and c.
-/// While
-/// \code
-///    varDecl(hasInitializer(cxxConstructExpr()))
+///   void f(int param) {
+///     int a = 0;
+///     int b = param;
+///     const int c = 0;
+///     const int d = param;
+///     int e = (0U);
+///     int f = (int)0.0;
+///     const int g = ((int)(((0))));
+///   }
 /// \endcode
-/// only match the declarations for b and c.
-AST_MATCHER_P(Expr, ignoringImplicit, internal::Matcher<Expr>,
-              InnerMatcher) {
+///
+/// The matcher
+/// \matcher{varDecl(hasInitializer(ignoringImplicit(integerLiteral())))}
+/// matches \match{int a = 0} and \match{const int c = 0},
+/// but not \nomatch{int e = (0U)} and \nomatch{((int)(((0)))}.
+/// The matcher
+/// \matcher{varDecl(hasInitializer(integerLiteral()))}
+/// matches \match{int a = 0} and \match{const int c = 0},
+/// but not \nomatch{int e = (0U)} and \nomatch{((int)(((0)))}.
+///
+/// The matcher
+/// \matcher{varDecl(hasInitializer(ignoringImplicit(declRefExpr())))}
+/// matches \match{int b = param} and \match{const int d = param}.
+/// The matcher
+/// \matcher{varDecl(hasInitializer(declRefExpr()))}
+/// matches neither \nomatch{int b = param} nor \nomatch{const int d = param},
+/// because an l-to-r-value cast happens.
+AST_MATCHER_P(Expr, ignoringImplicit, internal::Matcher<Expr>, InnerMatcher) {
   return InnerMatcher.matches(*Node.IgnoreImplicit(), Finder, Builder);
 }
 
@@ -902,24 +1079,26 @@ AST_MATCHER_P(Expr, ignoringImplicit, internal::Matcher<Expr>,
 /// Given
 /// \code
 ///   int arr[5];
-///   int a = 0;
+///   const int a = 0;
 ///   char b = 0;
 ///   const int c = a;
 ///   int *d = arr;
 ///   long e = (long) 0l;
 /// \endcode
-/// The matchers
-/// \code
-///    varDecl(hasInitializer(ignoringImpCasts(integerLiteral())))
-///    varDecl(hasInitializer(ignoringImpCasts(declRefExpr())))
-/// \endcode
-/// would match the declarations for a, b, c, and d, but not e.
-/// While
-/// \code
-///    varDecl(hasInitializer(integerLiteral()))
-///    varDecl(hasInitializer(declRefExpr()))
-/// \endcode
-/// only match the declarations for a.
+/// The matcher
+/// \matcher{varDecl(hasInitializer(ignoringImpCasts(integerLiteral())))}
+/// matches \match{type=name$a} and \match{type=name$b},
+/// but does not match \nomatch{type=name$e}.
+/// The matcher
+/// \matcher{varDecl(hasInitializer(ignoringImpCasts(declRefExpr())))}
+/// matches \match{type=name$c} and \match{type=name$d}.
+///
+/// The matcher
+/// \matcher{varDecl(hasInitializer(integerLiteral()))}
+/// matches \match{type=name$a},
+/// but does not match \nomatch{type=name$b} or \nomatch{type=name$e}.
+/// The matcher \matcher{varDecl(hasInitializer(declRefExpr()))}
+/// does not match \nomatch{type=name$c} or \nomatch{type=name$d}.
 AST_MATCHER_P(Expr, ignoringImpCasts,
               internal::Matcher<Expr>, InnerMatcher) {
   return InnerMatcher.matches(*Node.IgnoreImpCasts(), Finder, Builder);
@@ -936,12 +1115,14 @@ AST_MATCHER_P(Expr, ignoringImpCasts,
 ///   void* c = reinterpret_cast<char*>(0);
 ///   char d = char(0);
 /// \endcode
+/// \compile_args{-std=c++}
 /// The matcher
-///    varDecl(hasInitializer(ignoringParenCasts(integerLiteral())))
-/// would match the declarations for a, b, c, and d.
-/// while
-///    varDecl(hasInitializer(integerLiteral()))
-/// only match the declaration for a.
+/// \matcher{varDecl(hasInitializer(ignoringParenCasts(integerLiteral())))}
+/// matches \match{type=name$a}, \match{type=name$b}, \match{type=name$c}
+/// and \match{type=name$d}.
+/// The matcher
+/// \matcher{varDecl(hasInitializer(integerLiteral()))}
+/// matches \match{type=name$a}.
 AST_MATCHER_P(Expr, ignoringParenCasts, internal::Matcher<Expr>, InnerMatcher) {
   return InnerMatcher.matches(*Node.IgnoreParenCasts(), Finder, Builder);
 }
@@ -959,14 +1140,21 @@ AST_MATCHER_P(Expr, ignoringParenCasts, internal::Matcher<Expr>, InnerMatcher) {
 ///   int *d = (arr);
 ///   long e = ((long) 0l);
 /// \endcode
-/// The matchers
-///    varDecl(hasInitializer(ignoringParenImpCasts(integerLiteral())))
-///    varDecl(hasInitializer(ignoringParenImpCasts(declRefExpr())))
-/// would match the declarations for a, b, c, and d, but not e.
-/// while
-///    varDecl(hasInitializer(integerLiteral()))
-///    varDecl(hasInitializer(declRefExpr()))
-/// would only match the declaration for a.
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{varDecl(hasInitializer(ignoringParenImpCasts(integerLiteral())))}
+/// matches \match{type=name$a} and \match{type=name$b},
+/// but does not match \nomatch{type=name$e}.
+/// The matcher
+/// \matcher{varDecl(hasInitializer(ignoringParenImpCasts(declRefExpr())))}
+/// matches \match{type=name$c} and \match{type=name$d}.
+///
+/// The matcher
+/// \matcher{varDecl(hasInitializer(integerLiteral()))}
+/// matches \match{type=name$a},
+/// but does not match \nomatch{type=name$b} or \nomatch{type=name$e}.
+/// The matcher \matcher{varDecl(hasInitializer(declRefExpr()))}
+/// does not match \nomatch{type=name$c}, or \nomatch{type=name$d}.
 AST_MATCHER_P(Expr, ignoringParenImpCasts,
               internal::Matcher<Expr>, InnerMatcher) {
   return InnerMatcher.matches(*Node.IgnoreParenImpCasts(), Finder, Builder);
@@ -979,10 +1167,8 @@ AST_MATCHER_P(Expr, ignoringParenImpCasts,
 ///   void (*fp)(void);
 /// \endcode
 /// The matcher
-/// \code
-///   varDecl(hasType(pointerType(pointee(ignoringParens(functionType())))))
-/// \endcode
-/// would match the declaration for fp.
+/// \matcher{varDecl(hasType(pointerType(pointee(ignoringParens(functionType())))))}
+/// matches \match{type=name$fp}.
 AST_MATCHER_P_OVERLOAD(QualType, ignoringParens, internal::Matcher<QualType>,
                        InnerMatcher, 0) {
   return InnerMatcher.matches(Node.IgnoreParens(), Finder, Builder);
@@ -995,10 +1181,9 @@ AST_MATCHER_P_OVERLOAD(QualType, ignoringParens, internal::Matcher<QualType>,
 ///   const char* str = ("my-string");
 /// \endcode
 /// The matcher
-/// \code
-///   implicitCastExpr(hasSourceExpression(ignoringParens(stringLiteral())))
-/// \endcode
-/// would match the implicit cast resulting from the assignment.
+/// \matcher{implicitCastExpr(hasSourceExpression(ignoringParens(stringLiteral())))}
+/// would match the implicit cast resulting from the assignment
+/// \match{("my-string")}.
 AST_MATCHER_P_OVERLOAD(Expr, ignoringParens, internal::Matcher<Expr>,
                        InnerMatcher, 1) {
   const Expr *E = Node.IgnoreParens();
@@ -1015,9 +1200,13 @@ AST_MATCHER_P_OVERLOAD(Expr, ignoringParens, internal::Matcher<Expr>,
 /// sizeof is known.
 /// \code
 ///   template<typename T>
-///   void f(T x, T y) { sizeof(sizeof(T() + T()); }
+///   void f(T x, T y) { sizeof(T() + T()); }
 /// \endcode
-/// expr(isInstantiationDependent()) matches sizeof(sizeof(T() + T())
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{expr(isInstantiationDependent())}
+/// matches \match{sizeof(T() + T())},
+/// \match{(T() + T())},
+/// \match{T() + T()} and \match{count=2$T()}.
 AST_MATCHER(Expr, isInstantiationDependent) {
   return Node.isInstantiationDependent();
 }
@@ -1033,7 +1222,9 @@ AST_MATCHER(Expr, isInstantiationDependent) {
 ///     x + y;
 ///   }
 /// \endcode
-/// expr(isTypeDependent()) matches x + y
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{expr(isTypeDependent())}
+/// matches \match{x + y} and \match{x}.
 AST_MATCHER(Expr, isTypeDependent) { return Node.isTypeDependent(); }
 
 /// Matches expression that are value-dependent because they contain a
@@ -1044,7 +1235,9 @@ AST_MATCHER(Expr, isTypeDependent) { return Node.isTypeDependent(); }
 /// \code
 ///   template<int Size> int f() { return Size; }
 /// \endcode
-/// expr(isValueDependent()) matches return Size
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{expr(isValueDependent())}
+/// matches the return value \match{Size}.
 AST_MATCHER(Expr, isValueDependent) { return Node.isValueDependent(); }
 
 /// Matches templateSpecializationType, class template specializations,
@@ -1054,18 +1247,21 @@ AST_MATCHER(Expr, isValueDependent) { return Node.isValueDependent(); }
 /// Given
 /// \code
 ///   template<typename T, typename U> class A {};
-///   A<bool, int> b;
-///   A<int, bool> c;
+///   A<double, int> b;
+///   A<int, double> c;
 ///
 ///   template<typename T> void f() {}
 ///   void func() { f<int>(); };
 /// \endcode
-/// classTemplateSpecializationDecl(hasTemplateArgument(
-///     1, refersToType(asString("int"))))
-///   matches the specialization \c A<bool, int>
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{classTemplateSpecializationDecl(hasTemplateArgument(
+///     1, refersToType(asString("int"))))}
+/// matches the specialization \match{type=typestr$class A<double, int>}.
 ///
-/// functionDecl(hasTemplateArgument(0, refersToType(asString("int"))))
-///   matches the specialization \c f<int>
+/// The matcher \matcher{functionDecl(hasTemplateArgument(0,
+///                         refersToType(asString("int"))))}
+/// matches the specialization of \match{type=name$f}.
 AST_POLYMORPHIC_MATCHER_P2(
     hasTemplateArgument,
     AST_POLYMORPHIC_SUPPORTED_TYPES(ClassTemplateSpecializationDecl,
@@ -1086,8 +1282,10 @@ AST_POLYMORPHIC_MATCHER_P2(
 ///   template<typename T> struct C {};
 ///   C<int> c;
 /// \endcode
-/// classTemplateSpecializationDecl(templateArgumentCountIs(1))
-///   matches C<int>.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{classTemplateSpecializationDecl(templateArgumentCountIs(1))}
+/// matches \match{type=typestr$struct C<int>}.
 AST_POLYMORPHIC_MATCHER_P(
     templateArgumentCountIs,
     AST_POLYMORPHIC_SUPPORTED_TYPES(ClassTemplateSpecializationDecl,
@@ -1104,9 +1302,11 @@ AST_POLYMORPHIC_MATCHER_P(
 ///   template<typename T> struct A {};
 ///   A<X> a;
 /// \endcode
-/// classTemplateSpecializationDecl(hasAnyTemplateArgument(refersToType(
-///   recordType(hasDeclaration(recordDecl(hasName("X")))))))
-/// matches the specialization of \c struct A generated by \c A<X>.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{classTemplateSpecializationDecl(hasAnyTemplateArgument(refersToType(
+///             recordType(hasDeclaration(recordDecl(hasName("X")))))))}
+/// matches the specialization \match{type=typestr$struct A<struct X>}.
 AST_MATCHER_P(TemplateArgument, refersToType,
               internal::Matcher<QualType>, InnerMatcher) {
   if (Node.getKind() != TemplateArgument::Type)
@@ -1122,9 +1322,11 @@ AST_MATCHER_P(TemplateArgument, refersToType,
 ///   template<typename T> class Y {};
 ///   X<Y> xi;
 /// \endcode
-/// classTemplateSpecializationDecl(hasAnyTemplateArgument(
-///     refersToTemplate(templateName())))
-///   matches the specialization \c X<Y>
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{classTemplateSpecializationDecl(hasAnyTemplateArgument(
+///               refersToTemplate(templateName())))}
+/// matches the specialization \match{type=typestr$class X<Y>}
 AST_MATCHER_P(TemplateArgument, refersToTemplate,
               internal::Matcher<TemplateName>, InnerMatcher) {
   if (Node.getKind() != TemplateArgument::Template)
@@ -1141,10 +1343,13 @@ AST_MATCHER_P(TemplateArgument, refersToTemplate,
 ///   template<int(B::*next_ptr)> struct A {};
 ///   A<&B::next> a;
 /// \endcode
-/// classTemplateSpecializationDecl(hasAnyTemplateArgument(
-///     refersToDeclaration(fieldDecl(hasName("next")))))
-///   matches the specialization \c A<&B::next> with \c fieldDecl(...) matching
-///     \c B::next
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{classTemplateSpecializationDecl(hasAnyTemplateArgument(
+///     refersToDeclaration(fieldDecl(hasName("next")).bind("next"))))}
+/// matches the specialization \match{type=typestr$struct A<&B::next>}
+/// with \matcher{type=sub$fieldDecl(hasName("next"))} matching
+/// \match{type=name;sub=next$B::next}.
 AST_MATCHER_P(TemplateArgument, refersToDeclaration,
               internal::Matcher<Decl>, InnerMatcher) {
   if (Node.getKind() == TemplateArgument::Declaration)
@@ -1160,10 +1365,13 @@ AST_MATCHER_P(TemplateArgument, refersToDeclaration,
 ///   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
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{templateSpecializationType(hasAnyTemplateArgument(
+///   isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next")).bind("next")))))))}
+/// matches the specialization \match{type=typestr$A<&struct B::next>}
+/// with \matcher{type=sub$fieldDecl(hasName("next"))} matching
+/// \match{type=name;sub=next$B::next}.
 AST_MATCHER_P(TemplateArgument, isExpr, internal::Matcher<Expr>, InnerMatcher) {
   if (Node.getKind() == TemplateArgument::Expression)
     return InnerMatcher.matches(*Node.getAsExpr(), Finder, Builder);
@@ -1177,10 +1385,12 @@ AST_MATCHER_P(TemplateArgument, isExpr, internal::Matcher<Expr>, InnerMatcher) {
 ///   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.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{classTemplateSpecializationDecl(
+///   hasAnyTemplateArgument(isIntegral()))}
+/// matches the implicitly declared specialization
+/// \match{type=typestr$struct C<42>} from the instantiation for the type of the
+/// variable \c c .
 AST_MATCHER(TemplateArgument, isIntegral) {
   return Node.getKind() == TemplateArgument::Integral;
 }
@@ -1192,9 +1402,12 @@ AST_MATCHER(TemplateArgument, isIntegral) {
 ///   template<int T> struct C {};
 ///   C<42> c;
 /// \endcode
-/// classTemplateSpecializationDecl(
-///   hasAnyTemplateArgument(refersToIntegralType(asString("int"))))
-///   matches the implicit instantiation of C in C<42>.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{classTemplateSpecializationDecl(
+///   hasAnyTemplateArgument(refersToIntegralType(asString("int"))))}
+/// matches the implicitly declared specialization
+/// \match{type=typestr$struct C<42>} from the instantiation for the type of the
+/// variable \c c .
 AST_MATCHER_P(TemplateArgument, refersToIntegralType,
               internal::Matcher<QualType>, InnerMatcher) {
   if (Node.getKind() != TemplateArgument::Integral)
@@ -1213,9 +1426,12 @@ AST_MATCHER_P(TemplateArgument, refersToIntegralType,
 ///   template<int T> struct C {};
 ///   C<42> c;
 /// \endcode
-/// classTemplateSpecializationDecl(
-///   hasAnyTemplateArgument(equalsIntegralValue("42")))
-///   matches the implicit instantiation of C in C<42>.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{classTemplateSpecializationDecl(
+///   hasAnyTemplateArgument(equalsIntegralValue("42")))}
+/// matches the implicitly declared specialization
+/// \match{type=typestr$struct C<42>} from the instantiation for the type of the
+/// variable \c c .
 AST_MATCHER_P(TemplateArgument, equalsIntegralValue,
               std::string, Value) {
   if (Node.getKind() != TemplateArgument::Integral)
@@ -1231,23 +1447,28 @@ AST_MATCHER_P(TemplateArgument, equalsIntegralValue,
 ///     int x = 0;
 ///   }
 /// \endcode
-/// autoreleasePoolStmt(stmt()) matches the declaration of "x"
-/// inside the autorelease pool.
+/// \compile_args{-ObjC}
+/// The matcher \matcher{autoreleasePoolStmt(stmt())} matches the declaration of
+/// \match{int x = 0} inside the autorelease pool.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
        ObjCAutoreleasePoolStmt> autoreleasePoolStmt;
 
 /// Matches any value declaration.
 ///
-/// Example matches A, B, C and F
+/// Given
 /// \code
 ///   enum X { A, B, C };
 ///   void F();
+///   int V = 0;
 /// \endcode
+/// The matcher \matcher{valueDecl()}
+/// matches \match{A}, \match{B}, \match{C}, \match{void F()}
+/// and \match{int V = 0}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ValueDecl> valueDecl;
 
 /// Matches C++ constructor declarations.
 ///
-/// Example matches Foo::Foo() and Foo::Foo(int)
+/// Given
 /// \code
 ///   class Foo {
 ///    public:
@@ -1255,93 +1476,136 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ValueDecl> valueDecl;
 ///     Foo(int);
 ///     int DoSomething();
 ///   };
+///
+///   struct Bar {};
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxConstructorDecl()}
+/// matches \match{Foo()} and \match{Foo(int)}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, CXXConstructorDecl>
     cxxConstructorDecl;
 
 /// Matches explicit C++ destructor declarations.
 ///
-/// Example matches Foo::~Foo()
+/// Given
 /// \code
 ///   class Foo {
 ///    public:
 ///     virtual ~Foo();
 ///   };
+///
+///   struct Bar {};
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxDestructorDecl()}
+/// matches \match{virtual ~Foo()}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, CXXDestructorDecl>
     cxxDestructorDecl;
 
 /// Matches enum declarations.
 ///
-/// Example matches X
+/// Given
 /// \code
 ///   enum X {
 ///     A, B, C
 ///   };
 /// \endcode
+///
+/// The matcher \matcher{enumDecl()}
+/// matches the enum \match{type=name$X}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, EnumDecl> enumDecl;
 
 /// Matches enum constants.
 ///
-/// Example matches A, B, C
+/// Given
 /// \code
 ///   enum X {
 ///     A, B, C
 ///   };
 /// \endcode
+/// The matcher \matcher{enumConstantDecl()}
+/// matches \match{A}, \match{B} and \match{C}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, EnumConstantDecl>
     enumConstantDecl;
 
 /// Matches tag declarations.
 ///
-/// Example matches X, Z, U, S, E
+/// Given
 /// \code
 ///   class X;
 ///   template<class T> class Z {};
 ///   struct S {};
 ///   union U {};
-///   enum E {
-///     A, B, C
-///   };
+///   enum E { A, B, C };
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+///
+/// The matcher \matcher{tagDecl()}
+/// matches \match{class X}, \match{class Z {}}, the injected class name
+/// \match{class Z}, \match{struct S {}},
+/// the injected class name \match{struct S}, \match{union U {}},
+/// the injected class name \match{union U}
+/// and \match{enum E { A, B, C }}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, TagDecl> tagDecl;
 
 /// Matches method declarations.
 ///
-/// Example matches y
+/// Given
 /// \code
 ///   class X { void y(); };
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxMethodDecl()}
+/// matches \match{void y()}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, CXXMethodDecl>
     cxxMethodDecl;
 
 /// Matches conversion operator declarations.
 ///
-/// Example matches the operator.
+/// Given
 /// \code
 ///   class X { operator int() const; };
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxConversionDecl()}
+/// matches \match{operator int() const}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, CXXConversionDecl>
     cxxConversionDecl;
 
 /// Matches user-defined and implicitly generated deduction guide.
 ///
-/// Example matches the deduction guide.
+/// Given
 /// \code
 ///   template<typename T>
-///   class X { X(int) };
+///   class X { X(int); };
 ///   X(int) -> X<int>;
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++17-or-later}
+///
+/// The matcher \matcher{cxxDeductionGuideDecl()}
+/// matches the written deduction guide
+/// \match{type=typeofstr$auto (int) -> X<int>},
+/// the implicit copy deduction guide \match{type=typeofstr$auto (int) -> X<T>}
+/// and the implicitly declared deduction guide
+/// \match{type=typeofstr$auto (X<T>) -> X<T>}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, CXXDeductionGuideDecl>
     cxxDeductionGuideDecl;
 
 /// Matches concept declarations.
 ///
-/// Example matches integral
+/// Given
 /// \code
-///   template<typename T>
-///   concept integral = std::is_integral_v<T>;
+///   template<typename T> concept my_concept = true;
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++20-or-later}
+///
+/// The matcher \matcher{conceptDecl()}
+/// matches \match{template<typename T>
+/// concept my_concept = true}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ConceptDecl>
     conceptDecl;
 
@@ -1353,17 +1617,29 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ConceptDecl>
 /// Example matches a
 /// \code
 ///   int a;
+///   struct Foo {
+///     int x;
+///   };
+///   void bar(int val);
 /// \endcode
+///
+/// The matcher \matcher{varDecl()}
+/// matches \match{int a} and \match{int val}, but not \nomatch{int x}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, VarDecl> varDecl;
 
 /// Matches field declarations.
 ///
 /// Given
 /// \code
-///   class X { int m; };
+///   int a;
+///   struct Foo {
+///     int x;
+///   };
+///   void bar(int val);
 /// \endcode
-/// fieldDecl()
-///   matches 'm'.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{fieldDecl()}
+/// matches \match{int x}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, FieldDecl> fieldDecl;
 
 /// Matches indirect field declarations.
@@ -1372,17 +1648,20 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, FieldDecl> fieldDecl;
 /// \code
 ///   struct X { struct { int a; }; };
 /// \endcode
-/// indirectFieldDecl()
-///   matches 'a'.
+/// The matcher \matcher{indirectFieldDecl()}
+/// matches \match{a}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, IndirectFieldDecl>
     indirectFieldDecl;
 
 /// Matches function declarations.
 ///
-/// Example matches f
+/// Given
 /// \code
 ///   void f();
 /// \endcode
+///
+/// The matcher \matcher{functionDecl()}
+/// matches \match{void f()}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, FunctionDecl>
     functionDecl;
 
@@ -1392,6 +1671,10 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, FunctionDecl>
 /// \code
 ///   template<class T> void f(T t) {}
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+///
+/// The matcher \matcher{functionTemplateDecl()}
+/// matches \match{template<class T> void f(T t) {}}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, FunctionTemplateDecl>
     functionTemplateDecl;
 
@@ -1401,28 +1684,32 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, FunctionTemplateDecl>
 /// \code
 ///   class X { friend void foo(); };
 /// \endcode
-/// friendDecl()
-///   matches 'friend void foo()'.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{friendDecl()}
+/// matches \match{friend void foo()}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, FriendDecl> friendDecl;
 
 /// Matches statements.
 ///
 /// Given
 /// \code
-///   { ++a; }
+///   void foo(int a) { { ++a; } }
 /// \endcode
-/// stmt()
-///   matches both the compound statement '{ ++a; }' and '++a'.
+/// The matcher \matcher{stmt()}
+/// matches the function body itself \match{{ { ++a; } }}, the compound
+/// statement \match{{ ++a; }}, the expression \match{++a} and \match{a}.
 extern const internal::VariadicAllOfMatcher<Stmt> stmt;
 
 /// Matches declaration statements.
 ///
 /// Given
 /// \code
-///   int a;
+///   void foo() {
+///     int a;
+///   }
 /// \endcode
-/// declStmt()
-///   matches 'int a'.
+/// The matcher \matcher{declStmt()}
+/// matches \match{int a;}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, DeclStmt> declStmt;
 
 /// Matches member expressions.
@@ -1434,8 +1721,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, DeclStmt> declStmt;
 ///     int a; static int b;
 ///   };
 /// \endcode
-/// memberExpr()
-///   matches this->x, x, y.x, a, this->b
+/// \compile_args{-std=c++}
+/// The matcher \matcher{memberExpr()}
+/// matches \match{this->x}, \match{x}, \match{y.x}, \match{a}, \match{this->b}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, MemberExpr> memberExpr;
 
 /// Matches unresolved member expressions.
@@ -1448,8 +1736,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, MemberExpr> memberExpr;
 ///   };
 ///   template <class T> void h() { X x; x.f<T>(); x.g(); }
 /// \endcode
-/// unresolvedMemberExpr()
-///   matches x.f<T>
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{unresolvedMemberExpr()}
+/// matches \match{x.f<T>}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, UnresolvedMemberExpr>
     unresolvedMemberExpr;
 
@@ -1460,8 +1749,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, UnresolvedMemberExpr>
 /// \code
 ///   template <class T> void f() { T t; t.g(); }
 /// \endcode
-/// cxxDependentScopeMemberExpr()
-///   matches t.g
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{cxxDependentScopeMemberExpr()}
+///   matches \match{t.g}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
                                                    CXXDependentScopeMemberExpr>
     cxxDependentScopeMemberExpr;
@@ -1470,15 +1760,22 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt,
 ///
 /// Example matches x.y() and y()
 /// \code
-///   X x;
-///   x.y();
-///   y();
+///   struct X { void foo(); };
+///   void bar();
+///   void foobar() {
+///     X x;
+///     x.foo();
+///     bar();
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{callExpr()}
+/// matches \match{x.foo()} and \match{bar()};
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CallExpr> callExpr;
 
 /// Matches call expressions which were resolved using ADL.
 ///
-/// Example matches y(x) but not y(42) or NS::y(x).
+/// Given
 /// \code
 ///   namespace NS {
 ///     struct X {};
@@ -1494,25 +1791,46 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CallExpr> callExpr;
 ///     y(42); // Doesn't match
 ///     using NS::y;
 ///     y(x); // Found by both unqualified lookup and ADL, doesn't match
-//    }
+///    }
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{callExpr(usesADL())}
+/// matches \match{y(x)}, but not \nomatch{y(42)} or \nomatch{NS::y(x)}.
 AST_MATCHER(CallExpr, usesADL) { return Node.usesADL(); }
 
 /// Matches lambda expressions.
 ///
-/// Example matches [&](){return 5;}
+/// Given
 /// \code
-///   [&](){return 5;}
+///   void f() {
+///     []() { return 5; };
+///   }
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{lambdaExpr()} matches \match{[]() { return 5; }}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, LambdaExpr> lambdaExpr;
 
 /// Matches member call expressions.
 ///
-/// Example matches x.y()
+/// Given
 /// \code
-///   X x;
-///   x.y();
+///   struct X {
+///     void y();
+///     void m() { y(); }
+///   };
+///   void f();
+///   void g() {
+///     X x;
+///     x.y();
+///     f();
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxMemberCallExpr()} matches \match{x.y()} and
+/// \match{y()}, but not \nomatch{f()}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXMemberCallExpr>
     cxxMemberCallExpr;
 
@@ -1525,6 +1843,10 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXMemberCallExpr>
 /// \code
 ///   [[NSString alloc] initWithString:@"Hello"]
 /// \endcode
+/// \compile_args{-ObjC}
+///
+/// The matcher \matcher{objcMessageExpr()} matches
+/// \match{[[NSString alloc] initWithString:@"Hello"]}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCMessageExpr>
     objcMessageExpr;
 
@@ -1534,6 +1856,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCMessageExpr>
 /// \code
 ///   NSString *s = @"abcd";
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCStringLiteral>
     objcStringLiteral;
 
@@ -1544,6 +1867,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCStringLiteral>
 ///   @interface Foo
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCInterfaceDecl>
     objcInterfaceDecl;
 
@@ -1554,6 +1878,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCInterfaceDecl>
 ///   @implementation Foo
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCImplementationDecl>
     objcImplementationDecl;
 
@@ -1564,6 +1889,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCImplementationDecl>
 ///   @protocol FooDelegate
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCProtocolDecl>
     objcProtocolDecl;
 
@@ -1574,6 +1900,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCProtocolDecl>
 ///   @interface Foo (Additions)
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCCategoryDecl>
     objcCategoryDecl;
 
@@ -1584,6 +1911,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCCategoryDecl>
 ///   @implementation Foo (Additions)
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCCategoryImplDecl>
     objcCategoryImplDecl;
 
@@ -1599,6 +1927,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCCategoryImplDecl>
 ///   - (void)method {}
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCMethodDecl>
     objcMethodDecl;
 
@@ -1612,6 +1941,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCMethodDecl>
 ///     printf("%d", p);
 ///   })
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, BlockDecl>
     blockDecl;
 
@@ -1624,6 +1954,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, BlockDecl>
 ///   }
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCIvarDecl>
     objcIvarDecl;
 
@@ -1635,6 +1966,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCIvarDecl>
 ///   @property BOOL enabled;
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCPropertyDecl>
     objcPropertyDecl;
 
@@ -1644,6 +1976,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, ObjCPropertyDecl>
 /// \code
 ///   @throw obj;
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCAtThrowStmt>
     objcThrowStmt;
 
@@ -1654,6 +1987,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCAtThrowStmt>
 ///   @try {}
 ///   @catch (...) {}
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCAtTryStmt>
     objcTryStmt;
 
@@ -1664,6 +1998,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCAtTryStmt>
 ///   @try {}
 ///   @catch (...) {}
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCAtCatchStmt>
     objcCatchStmt;
 
@@ -1674,6 +2009,7 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCAtCatchStmt>
 ///   @try {}
 ///   @finally {}
 /// \endcode
+/// \compile_args{-ObjC}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCAtFinallyStmt>
     objcFinallyStmt;
 
@@ -1682,8 +2018,21 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCAtFinallyStmt>
 ///
 /// Example matches std::string()
 /// \code
-///   const std::string str = std::string();
+///   struct A { ~A(); };
+///   void f(A);
+///   void g(A&);
+///   void h() {
+///     A a = A{};
+///     f(A{});
+///     f(a);
+///     g(a);
+///   }
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{exprWithCleanups()} matches \match{A{}},
+/// \match{f(A{})} and \match{f(a)},
+/// but does not match passing \nomatch{g(a)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ExprWithCleanups>
     exprWithCleanups;
 
@@ -1693,17 +2042,29 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ExprWithCleanups>
 /// \code
 ///   int a[] = { 1, 2 };
 ///   struct B { int x, y; };
-///   B b = { 5, 6 };
+///   struct B b = { 5, 6 };
 /// \endcode
-/// initListExpr()
-///   matches "{ 1, 2 }" and "{ 5, 6 }"
+/// The matcher \matcher{initListExpr()}
+/// matches \match{{ 1, 2 }} and \match{{ 5, 6 }}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, InitListExpr>
     initListExpr;
 
 /// Matches the syntactic form of init list expressions
 /// (if expression have it).
-AST_MATCHER_P(InitListExpr, hasSyntacticForm,
-              internal::Matcher<Expr>, InnerMatcher) {
+///
+/// Given
+/// \code
+///   int a[] = { 1, 2 };
+///   struct B { int x, y; };
+///   struct B b = { 5, 6 };
+/// \endcode
+/// \compile_args{-std=c}
+///
+/// The matcher
+/// \matcher{initListExpr(hasSyntacticForm(expr().bind("syntactic")))}
+/// matches \match{{ 1, 2 }} and \match{{ 5, 6 }}.
+AST_MATCHER_P(InitListExpr, hasSyntacticForm, internal::Matcher<Expr>,
+              InnerMatcher) {
   const Expr *SyntForm = Node.getSyntacticForm();
   return (SyntForm != nullptr &&
           InnerMatcher.matches(*SyntForm, Finder, Builder));
@@ -1713,13 +2074,26 @@ AST_MATCHER_P(InitListExpr, hasSyntacticForm,
 ///
 /// Given
 /// \code
-///   std::vector<int> a({ 1, 2, 3 });
-///   std::vector<int> b = { 4, 5 };
+///   namespace std {
+///     template <typename T>
+///     class initializer_list {
+///       const T* begin;
+///       const T* end;
+///     };
+///   }
+///   template <typename T> class vector {
+///     public: vector(std::initializer_list<T>) {}
+///   };
+///
+///   vector<int> a({ 1, 2, 3 });
+///   vector<int> b = { 4, 5 };
 ///   int c[] = { 6, 7 };
-///   std::pair<int, int> d = { 8, 9 };
+///   struct pair { int x; int y; };
+///   pair d = { 8, 9 };
 /// \endcode
-/// cxxStdInitializerListExpr()
-///   matches "{ 1, 2, 3 }" and "{ 4, 5 }"
+/// \compile_args{-fno-delayed-template-parsing;-std=c++11-or-later,-nostdinc++}
+/// The matcher \matcher{cxxStdInitializerListExpr()}
+/// matches \match{{ 1, 2, 3 }} and \match{{ 4, 5 }}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
                                                    CXXStdInitializerListExpr>
     cxxStdInitializerListExpr;
@@ -1728,10 +2102,12 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt,
 ///
 /// Given
 /// \code
-///   point ptarray[10] = { [2].y = 1.0, [2].x = 2.0, [0].x = 1.0 };
+///   struct point { double x; double y; };
+///   struct point pt = { .x = 42.0 };
 /// \endcode
-/// implicitValueInitExpr()
-///   matches "[0].y" (implicitly)
+/// The matcher
+/// \matcher{initListExpr(has(implicitValueInitExpr().bind("implicit")))}
+/// matches \match{{ .x = 42.0 }}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ImplicitValueInitExpr>
     implicitValueInitExpr;
 
@@ -1748,8 +2124,12 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ImplicitValueInitExpr>
 ///     }
 ///   };
 /// \endcode
-/// parenListExpr() matches "*this" but NOT matches (a, b) because (a, b)
-/// has a predefined type and is a ParenExpr, not a ParenListExpr.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{parenListExpr()}
+/// matches \match{(*this)},
+/// but does not match \nomatch{(a, b)}
+/// because (a, b) has a predefined type and is a ParenExpr, not a
+/// ParenListExpr.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ParenListExpr>
     parenListExpr;
 
@@ -1761,8 +2141,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ParenListExpr>
 ///   struct A { static const int n = N; };
 ///   struct B : public A<42> {};
 /// \endcode
-/// substNonTypeTemplateParmExpr()
-///   matches "N" in the right-hand side of "static const int n = N;"
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{substNonTypeTemplateParmExpr()}
+/// matches \match{N} in the right-hand side of "static const int n = N;"
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
                                                    SubstNonTypeTemplateParmExpr>
     substNonTypeTemplateParmExpr;
@@ -1774,19 +2155,21 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt,
 ///   namespace X { int x; }
 ///   using X::x;
 /// \endcode
-/// usingDecl()
-///   matches \code using X::x \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{usingDecl()}
+///   matches \match{using X::x}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, UsingDecl> usingDecl;
 
 /// Matches using-enum declarations.
 ///
 /// Given
 /// \code
-///   namespace X { enum x {...}; }
+///   namespace X { enum x { val1, val2 }; }
 ///   using enum X::x;
 /// \endcode
-/// usingEnumDecl()
-///   matches \code using enum X::x \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{usingEnumDecl()}
+///   matches \match{using enum X::x}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, UsingEnumDecl>
     usingEnumDecl;
 
@@ -1797,8 +2180,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, UsingEnumDecl>
 ///   namespace X { int x; }
 ///   using namespace X;
 /// \endcode
-/// usingDirectiveDecl()
-///   matches \code using namespace X \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{usingDirectiveDecl()}
+///   matches \match{using namespace X}
 extern const internal::VariadicDynCastAllOfMatcher<Decl, UsingDirectiveDecl>
     usingDirectiveDecl;
 
@@ -1814,8 +2198,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, UsingDirectiveDecl>
 ///     foo<T>();
 ///   }
 /// \endcode
-/// unresolvedLookupExpr()
-///   matches \code foo<T>() \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{unresolvedLookupExpr()}
+/// matches \match{foo<T>}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, UnresolvedLookupExpr>
     unresolvedLookupExpr;
 
@@ -1828,8 +2213,9 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, UnresolvedLookupExpr>
 ///     using X::x;
 ///   };
 /// \endcode
-/// unresolvedUsingValueDecl()
-///   matches \code using X::x \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{unresolvedUsingValueDecl()}
+///   matches \match{using X::x}
 extern const internal::VariadicDynCastAllOfMatcher<Decl,
                                                    UnresolvedUsingValueDecl>
     unresolvedUsingValueDecl;
@@ -1847,79 +2233,109 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl,
 ///     using typename Base<T>::Foo;
 ///   };
 /// \endcode
-/// unresolvedUsingTypenameDecl()
-///   matches \code using Base<T>::Foo \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{unresolvedUsingTypenameDecl()}
+///   matches \match{using typename Base<T>::Foo}
 extern const internal::VariadicDynCastAllOfMatcher<Decl,
                                                    UnresolvedUsingTypenameDecl>
     unresolvedUsingTypenameDecl;
 
 /// Matches a constant expression wrapper.
 ///
-/// Example matches the constant in the case statement:
-///     (matcher = constantExpr())
+/// Given
 /// \code
-///   switch (a) {
-///   case 37: break;
+///   void f(int a) {
+///     switch (a) {
+///       case 37: break;
+///     }
 ///   }
 /// \endcode
+///
+/// The matcher \matcher{constantExpr()} matches \match{37}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ConstantExpr>
     constantExpr;
 
 /// Matches parentheses used in expressions.
 ///
-/// Example matches (foo() + 1)
+/// Given
 /// \code
 ///   int foo() { return 1; }
-///   int a = (foo() + 1);
+///   int bar() {
+///     int a = (foo() + 1);
+///   }
 /// \endcode
+///
+/// The matcher \matcher{parenExpr()} matches \match{(foo() + 1)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ParenExpr> parenExpr;
 
 /// Matches constructor call expressions (including implicit ones).
 ///
-/// Example matches string(ptr, n) and ptr within arguments of f
-///     (matcher = cxxConstructExpr())
+/// Given
 /// \code
+///   struct string {
+///     string(const char*);
+///     string(const char*s, int n);
+///   };
 ///   void f(const string &a, const string &b);
-///   char *ptr;
-///   int n;
-///   f(string(ptr, n), ptr);
+///   void foo(char *ptr, int n) {
+///     f(string(ptr, n), ptr);
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxConstructExpr()} matches \match{string(ptr, n)}
+/// and \match{ptr} within arguments of \c f .
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXConstructExpr>
     cxxConstructExpr;
 
 /// Matches unresolved constructor call expressions.
 ///
-/// Example matches T(t) in return statement of f
-///     (matcher = cxxUnresolvedConstructExpr())
+/// Given
 /// \code
 ///   template <typename T>
 ///   void f(const T& t) { return T(t); }
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+///
+/// The matcher \matcher{cxxUnresolvedConstructExpr()} matches
+/// \match{T(t)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
                                                    CXXUnresolvedConstructExpr>
     cxxUnresolvedConstructExpr;
 
 /// Matches implicit and explicit this expressions.
 ///
-/// Example matches the implicit this expression in "return i".
-///     (matcher = cxxThisExpr())
+/// Given
 /// \code
-/// struct foo {
-///   int i;
-///   int f() { return i; }
-/// };
+///   struct foo {
+///     int i;
+///     int f() { return i; }
+///     int g() { return this->i; }
+///   };
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxThisExpr()}
+/// matches \match{this} of \c this->i and the implicit \c this expression
+/// of \match{i}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXThisExpr>
     cxxThisExpr;
 
 /// Matches nodes where temporaries are created.
 ///
-/// Example matches FunctionTakesString(GetStringByValue())
-///     (matcher = cxxBindTemporaryExpr())
+/// Given
 /// \code
-///   FunctionTakesString(GetStringByValue());
-///   FunctionTakesStringByPointer(GetStringPointer());
+///   struct S {
+///     S() { }  // User defined constructor makes S non-POD.
+///     ~S() { } // User defined destructor makes it non-trivial.
+///   };
+///   void test() {
+///     const S &s_ref = S(); // Requires a CXXBindTemporaryExpr.
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxBindTemporaryExpr()}
+/// matches the constructor call \match{S()}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXBindTemporaryExpr>
     cxxBindTemporaryExpr;
 
@@ -1930,17 +2346,18 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXBindTemporaryExpr>
 ///   struct T {void func();};
 ///   T f();
 ///   void g(T);
+///   void foo() {
+///     T u(f());
+///     g(f());
+///     f().func();
+///     f(); // does not match
+///   }
 /// \endcode
-/// materializeTemporaryExpr() matches 'f()' in these statements
-/// \code
-///   T u(f());
-///   g(f());
-///   f().func();
-/// \endcode
-/// but does not match
-/// \code
-///   f();
-/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{materializeTemporaryExpr()} matches
+/// \match{std=c++14-or-earlier;count=3$f()} three times before C++17 and it
+/// matches \match{std=c++17-or-later$f()} time with C++17 and later, but
+/// it does not match the \nomatch{f()} in the last line in any version.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
                                                    MaterializeTemporaryExpr>
     materializeTemporaryExpr;
@@ -1949,20 +2366,34 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt,
 ///
 /// Given
 /// \code
-///   new X;
+///   void* operator new(decltype(sizeof(void*)));
+///   struct X {};
+///   void foo() {
+///     auto* x = new X;
+///   }
 /// \endcode
-/// cxxNewExpr()
-///   matches 'new X'.
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{cxxNewExpr()}
+/// matches \match{new X}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXNewExpr> cxxNewExpr;
 
 /// Matches delete expressions.
 ///
 /// Given
 /// \code
-///   delete X;
+///   void* operator new(decltype(sizeof(void*)));
+///   void operator delete(void*);
+///   struct X {};
+///   void foo() {
+///     auto* x = new X;
+///     delete x;
+///   }
 /// \endcode
-/// cxxDeleteExpr()
-///   matches 'delete X'.
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{cxxDeleteExpr()}
+/// matches \match{delete x}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXDeleteExpr>
     cxxDeleteExpr;
 
@@ -1976,13 +2407,16 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXDeleteExpr>
 ///   bool d() noexcept(noexcept(a()));
 ///   bool e = noexcept(b()) || noexcept(c());
 /// \endcode
-/// cxxNoexceptExpr()
-///   matches `noexcept(a())`, `noexcept(b())` and `noexcept(c())`.
-///   doesn't match the noexcept specifier in the declarations a, b, c or d.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{cxxNoexceptExpr()}
+/// matches \match{noexcept(a())}, \match{noexcept(b())} and
+/// \match{noexcept(c())}, but does not match the noexcept specifier in the
+/// declarations a, b, c or d.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXNoexceptExpr>
     cxxNoexceptExpr;
 
-/// Matches a loop initializing the elements of an array in a number of contexts:
+/// Matches a loop initializing the elements of an array in a number of
+/// contexts:
 ///  * in the implicit copy/move constructor for a class with an array member
 ///  * when a lambda-expression captures an array by value
 ///  * when a decomposition declaration decomposes an array
@@ -1991,33 +2425,34 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXNoexceptExpr>
 /// \code
 ///   void testLambdaCapture() {
 ///     int a[10];
-///     auto Lam1 = [a]() {
-///       return;
-///     };
+///     [a]() {};
 ///   }
 /// \endcode
-/// arrayInitLoopExpr() matches the implicit loop that initializes each element of
-/// the implicit array field inside the lambda object, that represents the array `a`
-/// captured by value.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{arrayInitLoopExpr()} matches the implicit loop that
+/// initializes each element of the implicit array field inside the lambda
+/// object, that represents the array \match{a} captured by value.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ArrayInitLoopExpr>
     arrayInitLoopExpr;
 
 /// The arrayInitIndexExpr consists of two subexpressions: a common expression
-/// (the source array) that is evaluated once up-front, and a per-element initializer
-/// that runs once for each array element. Within the per-element initializer,
-/// the current index may be obtained via an ArrayInitIndexExpr.
+/// (the source array) that is evaluated once up-front, and a per-element
+/// initializer that runs once for each array element. Within the per-element
+/// initializer, the current index may be obtained via an ArrayInitIndexExpr.
 ///
 /// Given
 /// \code
-///   void testStructBinding() {
+///   void testStructuredBinding() {
 ///     int a[2] = {1, 2};
 ///     auto [x, y] = a;
 ///   }
 /// \endcode
-/// arrayInitIndexExpr() matches the array index that implicitly iterates
-/// over the array `a` to copy each element to the anonymous array
-/// that backs the structured binding `[x, y]` elements of which are
-/// referred to by their aliases `x` and `y`.
+/// \compile_args{-std=c++17-or-later}
+///
+/// The matcher \matcher{type=none$arrayInitIndexExpr()} matches the array index
+/// that implicitly iterates over the array `a` to copy each element to the
+/// anonymous array that backs the structured binding.
+/// \match{}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ArrayInitIndexExpr>
     arrayInitIndexExpr;
 
@@ -2025,22 +2460,30 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ArrayInitIndexExpr>
 ///
 /// Given
 /// \code
-///   int i = a[1];
+///   void foo() {
+///     int a[2] = {0, 1};
+///     int i = a[1];
+///   }
 /// \endcode
-/// arraySubscriptExpr()
-///   matches "a[1]"
+/// The matcher \matcher{arraySubscriptExpr()}
+/// matches \match{a[1]}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ArraySubscriptExpr>
     arraySubscriptExpr;
 
 /// Matches the value of a default argument at the call site.
 ///
-/// Example matches the CXXDefaultArgExpr placeholder inserted for the
-///     default value of the second parameter in the call expression f(42)
-///     (matcher = cxxDefaultArgExpr())
+/// Given
 /// \code
 ///   void f(int x, int y = 0);
-///   f(42);
+///   void g() {
+///     f(42);
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{callExpr(has(cxxDefaultArgExpr()))}
+/// matches the \c CXXDefaultArgExpr placeholder inserted for the default value
+/// of the second parameter in the call expression \match{f(42)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXDefaultArgExpr>
     cxxDefaultArgExpr;
 
@@ -2051,13 +2494,18 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXDefaultArgExpr>
 /// Currently it does not match operators such as new delete.
 /// FIXME: figure out why these do not match?
 ///
-/// Example matches both operator<<((o << b), c) and operator<<(o, b)
-///     (matcher = cxxOperatorCallExpr())
+/// Given
 /// \code
+///   struct ostream;
 ///   ostream &operator<< (ostream &out, int i) { };
-///   ostream &o; int b = 1, c = 1;
-///   o << b << c;
+///   void f(ostream& o, int b, int c) {
+///     o << b << c;
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxOperatorCallExpr()} matches \match{o << b << c}
+/// and \match{o << b}.
 /// See also the binaryOperation() matcher for more-general matching of binary
 /// uses of this AST node.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXOperatorCallExpr>
@@ -2065,13 +2513,16 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXOperatorCallExpr>
 
 /// Matches C++17 fold expressions.
 ///
-/// Example matches `(0 + ... + args)`:
+/// Given
 /// \code
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
 ///       return (0 + ... + args);
 ///   }
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+///
+/// The matcher \matcher{cxxFoldExpr()} matches \match{(0 + ... + args)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXFoldExpr>
     cxxFoldExpr;
 
@@ -2079,17 +2530,21 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXFoldExpr>
 ///
 /// Example matches use of "<":
 /// \code
-///   #include <compare>
 ///   struct HasSpaceshipMem {
 ///     int a;
-///     constexpr auto operator<=>(const HasSpaceshipMem&) const = default;
+///     constexpr bool operator==(const HasSpaceshipMem&) const = default;
 ///   };
 ///   void compare() {
 ///     HasSpaceshipMem hs1, hs2;
-///     if (hs1 < hs2)
+///     if (hs1 != hs2)
 ///         return;
 ///   }
 /// \endcode
+/// \compile_args{-std=c++20-or-later}
+///
+/// The matcher \matcher{cxxRewrittenBinaryOperator()} matches
+/// \match{hs1 != hs2}.
+///
 /// See also the binaryOperation() matcher for more-general matching
 /// of this AST node.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
@@ -2098,25 +2553,34 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt,
 
 /// Matches expressions.
 ///
-/// Example matches x()
+/// Given
 /// \code
-///   void f() { x(); }
+///   int f(int x, int y) { return x + y; }
 /// \endcode
+///
+/// The matcher \matcher{expr()} matches \match{x + y} once,
+/// \match{count=2$x} twice and \match{count=2$y} twice, matching the
+/// \c DeclRefExpr , and the \c ImplicitCastExpr that does an l- to r-value
+/// cast.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, Expr> expr;
 
 /// Matches expressions that refer to declarations.
 ///
-/// Example matches x in if (x)
+/// Given
 /// \code
-///   bool x;
-///   if (x) {}
+///   void f(bool x) {
+///     if (x) {}
+///   }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+///
+/// The matcher \matcher{declRefExpr()} matches \match{x}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, DeclRefExpr>
     declRefExpr;
 
 /// Matches a reference to an ObjCIvar.
 ///
-/// Example: matches "a" in "init" method:
+/// Given
 /// \code
 /// @implementation A {
 ///   NSString *a;
@@ -2125,42 +2589,61 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, DeclRefExpr>
 ///   a = @"hello";
 /// }
 /// \endcode
+/// \compile_args{-ObjC}
+///
+/// The matcher \matcher{objcIvarRefExpr()} matches \match{a}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ObjCIvarRefExpr>
     objcIvarRefExpr;
 
 /// Matches a reference to a block.
 ///
-/// Example: matches "^{}":
+/// Given
 /// \code
 ///   void f() { ^{}(); }
 /// \endcode
+/// \compile_args{-ObjC}
+///
+/// The matcher \matcher{blockExpr()} matches \match{^{}}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, BlockExpr> blockExpr;
 
 /// Matches if statements.
 ///
-/// Example matches 'if (x) {}'
+/// Given
 /// \code
-///   if (x) {}
+///   void foo(int x) {
+///     if (x) {}
+///   }
 /// \endcode
+///
+/// The matcher \matcher{ifStmt()} matches \match{if (x) {}}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, IfStmt> ifStmt;
 
 /// Matches for statements.
 ///
-/// Example matches 'for (;;) {}'
+/// Given
 /// \code
-///   for (;;) {}
-///   int i[] =  {1, 2, 3}; for (auto a : i);
+///   void foo() {
+///     for (;;) {}
+///     int i[] =  {1, 2, 3}; for (auto a : i);
+///   }
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{forStmt()} matches \match{for (;;) {}},
+/// but not \nomatch{for (auto a : i);}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ForStmt> forStmt;
 
 /// Matches the increment statement of a for loop.
 ///
-/// Example:
-///     forStmt(hasIncrement(unaryOperator(hasOperatorName("++"))))
-/// matches '++x' in
+/// Given
 /// \code
-///     for (x; x < N; ++x) { }
+/// void foo(int N) {
+///     for (int x = 0; x < N; ++x) { }
+/// }
 /// \endcode
+/// The matcher
+/// \matcher{forStmt(hasIncrement(unaryOperator(hasOperatorName("++"))))}
+/// matches \match{for (int x = 0; x < N; ++x) { }}
 AST_MATCHER_P(ForStmt, hasIncrement, internal::Matcher<Stmt>,
               InnerMatcher) {
   const Stmt *const Increment = Node.getInc();
@@ -2170,12 +2653,14 @@ AST_MATCHER_P(ForStmt, hasIncrement, internal::Matcher<Stmt>,
 
 /// Matches the initialization statement of a for loop.
 ///
-/// Example:
-///     forStmt(hasLoopInit(declStmt()))
-/// matches 'int x = 0' in
+/// Given
 /// \code
+/// void foo(int N) {
 ///     for (int x = 0; x < N; ++x) { }
+/// }
 /// \endcode
+/// The matcher \matcher{forStmt(hasLoopInit(declStmt()))}
+/// matches \match{for (int x = 0; x < N; ++x) { }}
 AST_MATCHER_P(ForStmt, hasLoopInit, internal::Matcher<Stmt>,
               InnerMatcher) {
   const Stmt *const Init = Node.getInit();
@@ -2184,22 +2669,31 @@ AST_MATCHER_P(ForStmt, hasLoopInit, internal::Matcher<Stmt>,
 
 /// Matches range-based for statements.
 ///
-/// cxxForRangeStmt() matches 'for (auto a : i)'
+/// Given
 /// \code
-///   int i[] =  {1, 2, 3}; for (auto a : i);
-///   for(int j = 0; j < 5; ++j);
+///   void foo() {
+///     int i[] =  {1, 2, 3}; for (auto a : i);
+///     for(int j = 0; j < 5; ++j);
+///   }
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{cxxForRangeStmt()}
+/// matches \match{for (auto a : i);}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXForRangeStmt>
     cxxForRangeStmt;
 
 /// Matches the initialization statement of a for loop.
 ///
-/// Example:
-///     forStmt(hasLoopVariable(anything()))
-/// matches 'int x' in
+/// Given
 /// \code
+///   void foo() {
+///     int a[42] = {};
 ///     for (int x : a) { }
+///   }
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{cxxForRangeStmt(hasLoopVariable(anything()))}
+/// matches \match{for (int x : a) { }}
 AST_MATCHER_P(CXXForRangeStmt, hasLoopVariable, internal::Matcher<VarDecl>,
               InnerMatcher) {
   const VarDecl *const Var = Node.getLoopVariable();
@@ -2208,12 +2702,16 @@ AST_MATCHER_P(CXXForRangeStmt, hasLoopVariable, internal::Matcher<VarDecl>,
 
 /// Matches the range initialization statement of a for loop.
 ///
-/// Example:
-///     forStmt(hasRangeInit(anything()))
-/// matches 'a' in
+/// Given
 /// \code
+///   void foo() {
+///     int a[42] = {};
 ///     for (int x : a) { }
+///   }
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{cxxForRangeStmt(hasRangeInit(anything()))}
+/// matches \match{for (int x : a) { }}
 AST_MATCHER_P(CXXForRangeStmt, hasRangeInit, internal::Matcher<Expr>,
               InnerMatcher) {
   const Expr *const Init = Node.getRangeInit();
@@ -2224,40 +2722,52 @@ AST_MATCHER_P(CXXForRangeStmt, hasRangeInit, internal::Matcher<Expr>,
 ///
 /// Given
 /// \code
+/// void foo() {
 ///   while (true) {}
+/// }
 /// \endcode
-/// whileStmt()
-///   matches 'while (true) {}'.
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{whileStmt()}
+/// matches \match{while (true) {}}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, WhileStmt> whileStmt;
 
 /// Matches do statements.
 ///
 /// Given
 /// \code
+/// void foo() {
 ///   do {} while (true);
+/// }
 /// \endcode
-/// doStmt()
-///   matches 'do {} while(true)'
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{doStmt()}
+/// matches \match{do {} while (true)}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, DoStmt> doStmt;
 
 /// Matches break statements.
 ///
 /// Given
 /// \code
+/// void foo() {
 ///   while (true) { break; }
+/// }
 /// \endcode
-/// breakStmt()
-///   matches 'break'
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{breakStmt()}
+/// matches \match{break}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, BreakStmt> breakStmt;
 
 /// Matches continue statements.
 ///
 /// Given
 /// \code
+/// void foo() {
 ///   while (true) { continue; }
+/// }
 /// \endcode
-/// continueStmt()
-///   matches 'continue'
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{continueStmt()}
+/// matches \match{continue}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ContinueStmt>
     continueStmt;
 
@@ -2265,10 +2775,46 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ContinueStmt>
 ///
 /// Given
 /// \code
-///   while (true) { co_return; }
+///   namespace std {
+///   template <typename T = void>
+///   struct coroutine_handle {
+///       static constexpr coroutine_handle from_address(void* addr) {
+///         return {};
+///       }
+///   };
+///
+///   struct always_suspend {
+///       bool await_ready() const noexcept;
+///       bool await_resume() const noexcept;
+///       template <typename T>
+///       bool await_suspend(coroutine_handle<T>) const noexcept;
+///   };
+///
+///   template <typename T>
+///   struct coroutine_traits {
+///       using promise_type = T::promise_type;
+///   };
+///   }  // namespace std
+///
+///   struct generator {
+///       struct promise_type {
+///           void return_value(int v);
+///           std::always_suspend yield_value(int&&);
+///           std::always_suspend initial_suspend() const noexcept;
+///           std::always_suspend final_suspend() const noexcept;
+///           void unhandled_exception();
+///           generator get_return_object();
+///       };
+///   };
+///
+///   generator f() {
+///       co_return 10;
+///   }
+///
 /// \endcode
-/// coreturnStmt()
-///   matches 'co_return'
+/// \compile_args{-std=c++20-or-later}
+/// The matcher \matcher{coreturnStmt(has(integerLiteral()))}
+/// matches \match{co_return 10}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CoreturnStmt>
     coreturnStmt;
 
@@ -2276,44 +2822,55 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CoreturnStmt>
 ///
 /// Given
 /// \code
+/// int foo() {
 ///   return 1;
+/// }
 /// \endcode
-/// returnStmt()
-///   matches 'return 1'
+/// The matcher \matcher{returnStmt()}
+/// matches \match{return 1}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ReturnStmt> returnStmt;
 
 /// Matches goto statements.
 ///
 /// Given
 /// \code
+/// void bar();
+/// void foo() {
 ///   goto FOO;
 ///   FOO: bar();
+/// }
 /// \endcode
-/// gotoStmt()
-///   matches 'goto FOO'
+/// The matcher \matcher{gotoStmt()}
+/// matches \match{goto FOO}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, GotoStmt> gotoStmt;
 
 /// Matches label statements.
 ///
 /// Given
 /// \code
+/// void bar();
+/// void foo() {
 ///   goto FOO;
 ///   FOO: bar();
+/// }
 /// \endcode
-/// labelStmt()
-///   matches 'FOO:'
+/// The matcher \matcher{labelStmt()}
+/// matches \match{FOO: bar()}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, LabelStmt> labelStmt;
 
 /// Matches address of label statements (GNU extension).
 ///
 /// Given
 /// \code
+/// void bar();
+/// void foo() {
 ///   FOO: bar();
 ///   void *ptr = &&FOO;
-///   goto *bar;
+///   goto *ptr;
+/// }
 /// \endcode
-/// addrLabelExpr()
-///   matches '&&FOO'
+/// The matcher \matcher{addrLabelExpr()}
+/// matches \match{&&FOO}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, AddrLabelExpr>
     addrLabelExpr;
 
@@ -2321,116 +2878,147 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, AddrLabelExpr>
 ///
 /// Given
 /// \code
+/// void foo(int a) {
 ///   switch(a) { case 42: break; default: break; }
+/// }
 /// \endcode
-/// switchStmt()
-///   matches 'switch(a)'.
+/// The matcher \matcher{switchStmt()}
+/// matches \match{switch(a) { case 42: break; default: break; }}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, SwitchStmt> switchStmt;
 
 /// Matches case and default statements inside switch statements.
 ///
 /// Given
 /// \code
+/// void foo(int a) {
 ///   switch(a) { case 42: break; default: break; }
+/// }
 /// \endcode
-/// switchCase()
-///   matches 'case 42:' and 'default:'.
+/// The matcher \matcher{switchCase()}
+/// matches \match{case 42: break} and \match{default: break}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, SwitchCase> switchCase;
 
 /// Matches case statements inside switch statements.
 ///
 /// Given
 /// \code
+/// void foo(int a) {
 ///   switch(a) { case 42: break; default: break; }
+/// }
 /// \endcode
-/// caseStmt()
-///   matches 'case 42:'.
+/// The matcher \matcher{caseStmt()}
+/// matches \match{case 42: break}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CaseStmt> caseStmt;
 
 /// Matches default statements inside switch statements.
 ///
 /// Given
 /// \code
+/// void foo(int a) {
 ///   switch(a) { case 42: break; default: break; }
+/// }
 /// \endcode
-/// defaultStmt()
-///   matches 'default:'.
+/// The matcher \matcher{defaultStmt()}
+/// matches \match{default: break}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, DefaultStmt>
     defaultStmt;
 
 /// Matches compound statements.
 ///
-/// Example matches '{}' and '{{}}' in 'for (;;) {{}}'
+/// Given
 /// \code
-///   for (;;) {{}}
+/// void foo() { for (;;) {{}} }
 /// \endcode
+///
+/// The matcher \matcher{compoundStmt()} matches
+/// \match{{ for (;;) {{}} }}, \match{{{}}} and \match{{}}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CompoundStmt>
     compoundStmt;
 
 /// Matches catch statements.
 ///
 /// \code
+/// void foo() {
 ///   try {} catch(int i) {}
+/// }
 /// \endcode
-/// cxxCatchStmt()
-///   matches 'catch(int i)'
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxCatchStmt()}
+/// matches \match{catch(int i) {}}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXCatchStmt>
     cxxCatchStmt;
 
 /// Matches try statements.
 ///
 /// \code
+/// void foo() {
 ///   try {} catch(int i) {}
+/// }
 /// \endcode
-/// cxxTryStmt()
-///   matches 'try {}'
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxTryStmt()}
+/// matches \match{try {} catch(int i) {}}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXTryStmt> cxxTryStmt;
 
 /// Matches throw expressions.
 ///
 /// \code
+/// void foo() {
 ///   try { throw 5; } catch(int i) {}
+/// }
 /// \endcode
-/// cxxThrowExpr()
-///   matches 'throw 5'
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxThrowExpr()}
+/// matches \match{throw 5}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXThrowExpr>
     cxxThrowExpr;
 
 /// Matches null statements.
 ///
 /// \code
+/// void foo() {
 ///   foo();;
+/// }
 /// \endcode
-/// nullStmt()
-///   matches the second ';'
+/// The matcher \matcher{nullStmt()}
+/// matches the second \match{;}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, NullStmt> nullStmt;
 
 /// Matches asm statements.
 ///
 /// \code
+/// void foo() {
 ///  int i = 100;
-///   __asm("mov al, 2");
+///   __asm("mov %al, 2");
+/// }
 /// \endcode
-/// asmStmt()
-///   matches '__asm("mov al, 2")'
+/// The matcher \matcher{asmStmt()}
+/// matches \match{__asm("mov %al, 2")}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, AsmStmt> asmStmt;
 
 /// Matches bool literals.
 ///
 /// Example matches true
 /// \code
-///   true
+///   bool Flag = true;
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+///
+/// The matcher \matcher{cxxBoolLiteral()} matches \match{true}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXBoolLiteralExpr>
     cxxBoolLiteral;
 
 /// Matches string literals (also matches wide string literals).
 ///
-/// Example matches "abcd", L"abcd"
+/// Given
 /// \code
 ///   char *s = "abcd";
 ///   wchar_t *ws = L"abcd";
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{stringLiteral()} matches \match{"abcd"} and
+/// \match{L"abcd"}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, StringLiteral>
     stringLiteral;
 
@@ -2439,11 +3027,15 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, StringLiteral>
 /// Not matching Hex-encoded chars (e.g. 0x1234, which is a IntegerLiteral),
 /// though.
 ///
-/// Example matches 'a', L'a'
+/// Given
 /// \code
 ///   char ch = 'a';
 ///   wchar_t chw = L'a';
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{characterLiteral()} matches \match{'a'} and
+/// \match{L'a'}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CharacterLiteral>
     characterLiteral;
 
@@ -2451,31 +3043,80 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CharacterLiteral>
 /// 1, 1L, 0x1 and 1U.
 ///
 /// Does not match character-encoded integers such as L'a'.
+///
+/// Given
+/// \code
+///   int a = 1;
+///   int b = 1L;
+///   int c = 0x1;
+///   int d = 1U;
+///   int e = 1.0;
+/// \endcode
+///
+/// The matcher \matcher{integerLiteral()} matches
+/// \match{1}, \match{1L}, \match{0x1} and \match{1U}, but does not match
+/// \nomatch{1.0}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, IntegerLiteral>
     integerLiteral;
 
 /// Matches float literals of all sizes / encodings, e.g.
 /// 1.0, 1.0f, 1.0L and 1e10.
 ///
-/// Does not match implicit conversions such as
+/// Given
 /// \code
-///   float a = 10;
+///   int a = 1.0;
+///   int b = 1.0F;
+///   int c = 1.0L;
+///   int d = 1e10;
+///   int e = 1;
 /// \endcode
+///
+/// The matcher \matcher{floatLiteral()} matches
+/// \match{1.0}, \match{1.0F}, \match{1.0L} and \match{1e10}, but does not match
+/// \nomatch{1}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, FloatingLiteral>
     floatLiteral;
 
 /// Matches imaginary literals, which are based on integer and floating
 /// point literals e.g.: 1i, 1.0i
+///
+/// Given
+/// \code
+///   auto a = 1i;
+///   auto b = 1.0i;
+/// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{imaginaryLiteral()} matches \match{1i} and
+/// \match{1.0i}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ImaginaryLiteral>
     imaginaryLiteral;
 
 /// Matches fixed point literals
+///
+/// Given
+/// \code
+///   void f() {
+///     0.0k;
+///   }
+/// \endcode
+/// \compile_args{-ffixed-point}
+///
+/// The matcher \matcher{type=none$fixedPointLiteral()} matches \match{0.0k}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, FixedPointLiteral>
     fixedPointLiteral;
 
 /// Matches user defined literal operator call.
 ///
 /// Example match: "foo"_suffix
+/// Given
+/// \code
+///   float operator ""_foo(long double);
+///   float a = 1234.5_foo;
+/// \endcode
+/// \compile_args{-std=c++11}
+///
+/// The matcher \matcher{userDefinedLiteral()} matches \match{1234.5_foo}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, UserDefinedLiteral>
     userDefinedLiteral;
 
@@ -2483,9 +3124,12 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, UserDefinedLiteral>
 ///
 /// Example match: {1}, (1, 2)
 /// \code
-///   int array[4] = {1};
-///   vector int myvec = (vector int)(1, 2);
+///   struct vector { int x; int y; };
+///   struct vector myvec = (struct vector){ 1, 2 };
 /// \endcode
+///
+/// The matcher \matcher{compoundLiteralExpr()}
+/// matches \match{(struct vector){ 1, 2 }}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CompoundLiteralExpr>
     compoundLiteralExpr;
 
@@ -2493,78 +3137,297 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CompoundLiteralExpr>
 ///
 /// Given
 /// \code
-///   co_await 1;
+///   namespace std {
+///   template <typename T = void>
+///   struct coroutine_handle {
+///       static constexpr coroutine_handle from_address(void* addr) {
+///         return {};
+///       }
+///   };
+///
+///   struct always_suspend {
+///       bool await_ready() const noexcept;
+///       bool await_resume() const noexcept;
+///       template <typename T>
+///       bool await_suspend(coroutine_handle<T>) const noexcept;
+///   };
+///
+///   template <typename T>
+///   struct coroutine_traits {
+///       using promise_type = T::promise_type;
+///   };
+///   }  // namespace std
+///
+///   struct generator {
+///       struct promise_type {
+///           std::always_suspend yield_value(int&&);
+///           std::always_suspend initial_suspend() const noexcept;
+///           std::always_suspend final_suspend() const noexcept;
+///           void return_void();
+///           void unhandled_exception();
+///           generator get_return_object();
+///       };
+///   };
+///
+///   std::always_suspend h();
+///
+///   generator g() { co_await h(); }
 /// \endcode
-/// coawaitExpr()
-///   matches 'co_await 1'
+/// \compile_args{-std=c++20-or-later}
+/// The matcher
+/// \matcher{coawaitExpr(has(callExpr(callee(functionDecl(hasName("h"))))))}
+/// matches \match{co_await h()}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CoawaitExpr>
     coawaitExpr;
+
 /// Matches co_await expressions where the type of the promise is dependent
+///
+/// Given
+/// \code
+///   namespace std {
+///   template <typename T = void>
+///   struct coroutine_handle {
+///       static constexpr coroutine_handle from_address(void* addr) {
+///         return {};
+///       }
+///   };
+///
+///   struct always_suspend {
+///       bool await_ready() const noexcept;
+///       bool await_resume() const noexcept;
+///       template <typename T>
+///       bool await_suspend(coroutine_handle<T>) const noexcept;
+///   };
+///
+///   template <typename T>
+///   struct coroutine_traits {
+///       using promise_type = T::promise_type;
+///   };
+///   }  // namespace std
+///
+///   template <typename T>
+///   struct generator {
+///       struct promise_type {
+///           std::always_suspend yield_value(int&&);
+///           std::always_suspend initial_suspend() const noexcept;
+///           std::always_suspend final_suspend() const noexcept;
+///           void return_void();
+///           void unhandled_exception();
+///           generator get_return_object();
+///       };
+///   };
+///
+///   template <typename T>
+///   std::always_suspend h();
+///
+///   template <>
+///   std::always_suspend h<void>();
+///
+///   template<typename T>
+///   generator<T> g() { co_await h<T>(); }
+/// \endcode
+/// \compile_args{-std=c++20-or-later}
+/// The matcher \matcher{dependentCoawaitExpr()}
+/// matches \match{co_await h<T>()}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, DependentCoawaitExpr>
     dependentCoawaitExpr;
+
 /// Matches co_yield expressions.
 ///
 /// Given
 /// \code
-///   co_yield 1;
+///   namespace std {
+///   template <typename T = void>
+///   struct coroutine_handle {
+///       static constexpr coroutine_handle from_address(void* addr) {
+///         return {};
+///       }
+///   };
+///
+///   struct always_suspend {
+///       bool await_ready() const noexcept;
+///       bool await_resume() const noexcept;
+///       template <typename T>
+///       bool await_suspend(coroutine_handle<T>) const noexcept;
+///   };
+///
+///   template <typename T>
+///   struct coroutine_traits {
+///       using promise_type = T::promise_type;
+///   };
+///   }  // namespace std
+///
+///   struct generator {
+///       struct promise_type {
+///           std::always_suspend yield_value(int&&);
+///           std::always_suspend initial_suspend() const noexcept;
+///           std::always_suspend final_suspend() const noexcept;
+///           void return_void();
+///           void unhandled_exception();
+///           generator get_return_object();
+///       };
+///   };
+///
+///   generator f() {
+///       while (true) {
+///           co_yield 10;
+///       }
+///   }
 /// \endcode
-/// coyieldExpr()
-///   matches 'co_yield 1'
+/// \compile_args{-std=c++20-or-later}
+/// The matcher \matcher{coyieldExpr()}
+/// matches \match{co_yield 10}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CoyieldExpr>
     coyieldExpr;
 
 /// Matches coroutine body statements.
 ///
-/// coroutineBodyStmt() matches the coroutine below
+/// Given
 /// \code
-///   generator<int> gen() {
-///     co_return;
-///   }
+///   namespace std {
+///   template <typename T = void>
+///   struct coroutine_handle {
+///       static constexpr coroutine_handle from_address(void* addr) {
+///         return {};
+///       }
+///   };
+///
+///   struct suspend_always {
+///       bool await_ready() const noexcept;
+///       bool await_resume() const noexcept;
+///       template <typename T>
+///       bool await_suspend(coroutine_handle<T>) const noexcept;
+///   };
+///
+///   template <typename...>
+///   struct coroutine_traits {
+///       struct promise_type {
+///           std::suspend_always initial_suspend() const noexcept;
+///           std::suspend_always final_suspend() const noexcept;
+///           void return_void();
+///           void unhandled_exception();
+///           coroutine_traits get_return_object();
+///       };
+///   };
+///   }  // namespace std
+///
+///   void f() { while (true) { co_return; } }
+///
 /// \endcode
+/// \compile_args{-std=c++20-or-later}
+///
+/// The matcher \matcher{coroutineBodyStmt()} matches
+/// \match{{ while (true) { co_return; } }}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CoroutineBodyStmt>
     coroutineBodyStmt;
 
 /// Matches nullptr literal.
+///
+/// Given
+/// \code
+///   int a = 0;
+///   int* b = 0;
+///   int *c = nullptr;
+/// \endcode
+/// \compile_args{-std=c++11,c23-or-later}
+///
+/// The matcher \matcher{cxxNullPtrLiteralExpr()} matches \match{nullptr}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXNullPtrLiteralExpr>
     cxxNullPtrLiteralExpr;
 
 /// Matches GNU __builtin_choose_expr.
-extern const internal::VariadicDynCastAllOfMatcher<Stmt, ChooseExpr>
-    chooseExpr;
+///
+/// Given
+/// \code
+///   void f() { (void)__builtin_choose_expr(1, 2, 3); }
+/// \endcode
+///
+/// The matcher \matcher{chooseExpr()} matches
+/// \match{__builtin_choose_expr(1, 2, 3)}.
+extern const internal::VariadicDynCastAllOfMatcher<Stmt, ChooseExpr> chooseExpr;
 
 /// Matches builtin function __builtin_convertvector.
+///
+/// Given
+/// \code
+///   typedef double vector4double __attribute__((__vector_size__(32)));
+///   typedef float  vector4float  __attribute__((__vector_size__(16)));
+///   vector4float vf;
+///   void f() { (void)__builtin_convertvector(vf, vector4double); }
+/// \endcode
+///
+/// The matcher \matcher{convertVectorExpr()} matches
+/// \match{__builtin_convertvector(vf, vector4double)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ConvertVectorExpr>
     convertVectorExpr;
 
 /// Matches GNU __null expression.
+///
+/// Given
+/// \code
+///   auto val = __null;
+/// \endcode
+/// \compile_args{-std=c++11}
+///
+/// The matcher \matcher{gnuNullExpr()} matches \match{__null}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, GNUNullExpr>
     gnuNullExpr;
 
 /// Matches C11 _Generic expression.
+///
+/// Given
+/// \code
+///   double fdouble(double);
+///   float ffloat(float);
+///   #define GENERIC_MACRO(X) _Generic((X), double: fdouble, float: ffloat)(X)
+///
+///   void f() {
+///       GENERIC_MACRO(0.0);
+///       GENERIC_MACRO(0.0F);
+///   }
+/// \endcode
+/// \compile_args{-std=c}
+///
+/// The matcher \matcher{type=none$genericSelectionExpr()} matches
+/// the generic selection expression that is expanded in
+/// \match{GENERIC_MACRO(0.0)} and \match{GENERIC_MACRO(0.0F)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, GenericSelectionExpr>
     genericSelectionExpr;
 
 /// Matches atomic builtins.
-/// Example matches __atomic_load_n(ptr, 1)
+///
+/// Given
 /// \code
 ///   void foo() { int *ptr; __atomic_load_n(ptr, 1); }
 /// \endcode
+///
+/// The matcher \matcher{atomicExpr()} matches \match{__atomic_load_n(ptr, 1)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, AtomicExpr> atomicExpr;
 
 /// Matches statement expression (GNU extension).
 ///
-/// Example match: ({ int X = 4; X; })
+/// Given
 /// \code
-///   int C = ({ int X = 4; X; });
+///   void f() {
+///     int C = ({ int X = 4; X; });
+///   }
 /// \endcode
+///
+/// The matcher \matcher{stmtExpr()} matches \match{({ int X = 4; X; })}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, StmtExpr> stmtExpr;
 
 /// Matches binary operator expressions.
 ///
-/// Example matches a || b
+/// Given
 /// \code
-///   !(a || b)
+///   void foo(bool a, bool b) {
+///     !(a || b);
+///   }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+///
+/// The matcher \matcher{binaryOperator()} matches \match{a || b}.
+///
 /// See also the binaryOperation() matcher for more-general matching.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, BinaryOperator>
     binaryOperator;
@@ -2573,26 +3436,39 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, BinaryOperator>
 ///
 /// Example matches !a
 /// \code
-///   !a || b
+///   void foo(bool a, bool b) {
+///     !a || b;
+///   }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+///
+/// The matcher \matcher{unaryOperator()} matches \match{!a}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, UnaryOperator>
     unaryOperator;
 
 /// Matches conditional operator expressions.
 ///
-/// Example matches a ? b : c
+/// Given
 /// \code
-///   (a ? b : c) + 42
+///   int f(int a, int b, int c) {
+///     return (a ? b : c) + 42;
+///   }
 /// \endcode
+///
+/// The matcher \matcher{conditionalOperator()} matches \match{a ? b : c}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ConditionalOperator>
     conditionalOperator;
 
 /// Matches binary conditional operator expressions (GNU extension).
 ///
-/// Example matches a ?: b
+/// Given
 /// \code
-///   (a ?: b) + 42;
+///   int f(int a, int b) {
+///     return (a ?: b) + 42;
+///   }
 /// \endcode
+///
+/// The matcher \matcher{binaryConditionalOperator()} matches \match{a ?: b}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
                                                    BinaryConditionalOperator>
     binaryConditionalOperator;
@@ -2601,26 +3477,32 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt,
 /// to reference another expressions and can be met
 /// in BinaryConditionalOperators, for example.
 ///
-/// Example matches 'a'
+/// Given
 /// \code
-///   (a ?: c) + 42;
+///   int f(int a, int b) {
+///     return (a ?: b) + 42;
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{opaqueValueExpr()} matches \match{count=2$a} twice,
+/// once for the check and once for the expression of the true path.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, OpaqueValueExpr>
     opaqueValueExpr;
 
 /// Matches a C++ static_assert declaration.
 ///
-/// Example:
-///   staticAssertDecl()
-/// matches
-///   static_assert(sizeof(S) == sizeof(int))
-/// in
+/// Given
 /// \code
 ///   struct S {
 ///     int x;
 ///   };
 ///   static_assert(sizeof(S) == sizeof(int));
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{staticAssertDecl()}
+/// matches \match{static_assert(sizeof(S) == sizeof(int))}.
 extern const internal::VariadicDynCastAllOfMatcher<Decl, StaticAssertDecl>
     staticAssertDecl;
 
@@ -2634,6 +3516,10 @@ extern const internal::VariadicDynCastAllOfMatcher<Decl, StaticAssertDecl>
 /// \code
 ///   void* p = reinterpret_cast<char*>(&p);
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxReinterpretCastExpr()}
+/// matches \match{reinterpret_cast<char*>(&p)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXReinterpretCastExpr>
     cxxReinterpretCastExpr;
 
@@ -2642,49 +3528,56 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXReinterpretCastExpr>
 /// \see hasDestinationType
 /// \see reinterpretCast
 ///
-/// Example:
-///   cxxStaticCastExpr()
-/// matches
-///   static_cast<long>(8)
-/// in
+/// Given
 /// \code
 ///   long eight(static_cast<long>(8));
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxStaticCastExpr()}
+/// matches \match{static_cast<long>(8)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXStaticCastExpr>
     cxxStaticCastExpr;
 
 /// Matches a dynamic_cast expression.
 ///
-/// Example:
-///   cxxDynamicCastExpr()
-/// matches
-///   dynamic_cast<D*>(&b);
-/// in
+/// Given
 /// \code
 ///   struct B { virtual ~B() {} }; struct D : B {};
 ///   B b;
 ///   D* p = dynamic_cast<D*>(&b);
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxDynamicCastExpr()}
+/// matches \match{dynamic_cast<D*>(&b)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXDynamicCastExpr>
     cxxDynamicCastExpr;
 
 /// Matches a const_cast expression.
 ///
-/// Example: Matches const_cast<int*>(&r) in
+/// Given
 /// \code
 ///   int n = 42;
 ///   const int &r(n);
 ///   int* p = const_cast<int*>(&r);
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxConstCastExpr()}
+/// matches \match{const_cast<int*>(&r)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXConstCastExpr>
     cxxConstCastExpr;
 
 /// Matches a C-style cast expression.
 ///
-/// Example: Matches (int) 2.2f in
+/// Given
 /// \code
 ///   int i = (int) 2.2f;
 /// \endcode
+///
+/// The matcher \matcher{cStyleCastExpr()}
+/// matches \match{(int) 2.2f}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CStyleCastExpr>
     cStyleCastExpr;
 
@@ -2701,14 +3594,25 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CStyleCastExpr>
 ///
 /// \see hasDestinationType.
 ///
-/// Example: matches all five of the casts in
 /// \code
-///   int((int)(reinterpret_cast<int>(static_cast<int>(const_cast<int>(42)))))
-/// \endcode
-/// but does not match the implicit conversion in
-/// \code
-///   long ell = 42;
-/// \endcode
+///   struct S {};
+///   const S* s;
+///   S* s2 = const_cast<S*>(s);
+///
+///   const int val = 0;
+///   char val0 = val;
+///   char val1 = (char)val;
+///   char val2 = static_cast<char>(val);
+///   int* val3 = reinterpret_cast<int*>(val);
+///   char val4 = char(val);
+/// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{explicitCastExpr()}
+/// matches \match{(char)val}, \match{static_cast<char>(val)},
+/// \match{reinterpret_cast<int*>(val)}, \match{const_cast<S*>(s)}
+/// and \match{char(val)}, but not the initialization of \c val0 with
+/// \nomatch{val}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ExplicitCastExpr>
     explicitCastExpr;
 
@@ -2716,41 +3620,89 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, ExplicitCastExpr>
 ///
 /// This matches many different places, including function call return value
 /// eliding, as well as any type conversions.
+///
+/// \code
+/// void f(int);
+/// void g(int val1, int val2) {
+///   unsigned int a = val1;
+///   f(val2);
+/// }
+/// \endcode
+///
+/// The matcher \matcher{implicitCastExpr()}
+/// matches \match{count=2$val1} for the implicit cast from an l- to an r-value
+/// and for the cast to \c{unsigned int}, \match{f} for the function pointer
+/// decay, and \match{val2} for the cast from an l- to an r-value.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, ImplicitCastExpr>
     implicitCastExpr;
 
 /// Matches any cast nodes of Clang's AST.
 ///
-/// Example: castExpr() matches each of the following:
-/// \code
-///   (int) 3;
-///   const_cast<Expr *>(SubExpr);
-///   char c = 0;
-/// \endcode
-/// but does not match
+/// Given
 /// \code
-///   int i = (0);
-///   int k = 0;
+///   struct S {};
+///   const S* s;
+///   S* s2 = const_cast<S*>(s);
+///
+///   const int val = 0;
+///   char val0 = 1;
+///   char val1 = (char)2;
+///   char val2 = static_cast<char>(3);
+///   int* val3 = reinterpret_cast<int*>(4);
+///   char val4 = char(5);
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{castExpr()}
+/// matches
+/// \match{const_cast<S*>(s)} and the implicit l- to r-value cast for \match{s},
+/// the implicit cast to \c char for the initializer \match{1},
+/// the c-style cast \match{(char)2} and it's implicit cast to \c char
+/// (part of the c-style cast) \match{2},
+/// \match{static_cast<char>(3)} and it's implicit cast to \c char
+/// (part of the \c static_cast) \match{3},
+/// \match{reinterpret_cast<int*>(4)},
+/// \match{char(5)} and it's implicit cast to \c char
+/// (part of the functional cast) \match{5}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CastExpr> castExpr;
 
 /// Matches functional cast expressions
 ///
-/// Example: Matches Foo(bar);
+/// Given
 /// \code
-///   Foo f = bar;
-///   Foo g = (Foo) bar;
-///   Foo h = Foo(bar);
+///   struct Foo {
+///     Foo(int x);
+///   };
+///
+///   void foo(int bar) {
+///     Foo f = bar;
+///     Foo g = (Foo) bar;
+///     Foo h = Foo(bar);
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxFunctionalCastExpr()}
+/// matches \match{Foo(bar)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXFunctionalCastExpr>
     cxxFunctionalCastExpr;
 
 /// Matches functional cast expressions having N != 1 arguments
 ///
-/// Example: Matches Foo(bar, bar)
+/// Given
 /// \code
-///   Foo h = Foo(bar, bar);
+///   struct Foo {
+///     Foo(int x, int y);
+///   };
+///
+///   void foo(int bar) {
+///     Foo h = Foo(bar, bar);
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxTemporaryObjectExpr()}
+/// matches \match{Foo(bar, bar)}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXTemporaryObjectExpr>
     cxxTemporaryObjectExpr;
 
@@ -2758,17 +3710,27 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CXXTemporaryObjectExpr>
 ///
 /// Example: Matches __func__
 /// \code
-///   printf("%s", __func__);
+///   void f() {
+///     const char* func_name = __func__;
+///   }
 /// \endcode
+///
+/// The matcher \matcher{predefinedExpr()}
+/// matches \match{__func__}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, PredefinedExpr>
     predefinedExpr;
 
 /// Matches C99 designated initializer expressions [C99 6.7.8].
 ///
-/// Example: Matches { [2].y = 1.0, [0].x = 1.0 }
+/// Example: Given
 /// \code
-///   point ptarray[10] = { [2].y = 1.0, [0].x = 1.0 };
+///   struct point2 { double x; double y; };
+///   struct point2 ptarray[10] = { [0].x = 1.0 };
+///   struct point2 pt = { .x = 2.0 };
 /// \endcode
+///
+/// The matcher \matcher{designatedInitExpr()}
+/// matches \match{[0].x = 1.0} and \match{.x = 2.0}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, DesignatedInitExpr>
     designatedInitExpr;
 
@@ -2777,23 +3739,53 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, DesignatedInitExpr>
 ///
 /// Example: Given
 /// \code
-///   point ptarray[10] = { [2].y = 1.0, [0].x = 1.0 };
-///   point ptarray2[10] = { [2].y = 1.0, [2].x = 0.0, [0].x = 1.0 };
+///   struct point2 { double x; double y; };
+///   struct point2 ptarray[10] = { [0].x = 1.0 };
+///   struct point2 pt = { .x = 2.0 };
 /// \endcode
-/// designatorCountIs(2)
-///   matches '{ [2].y = 1.0, [0].x = 1.0 }',
-///   but not '{ [2].y = 1.0, [2].x = 0.0, [0].x = 1.0 }'.
+///
+/// The matcher \matcher{designatedInitExpr(designatorCountIs(2))}
+/// matches \match{[0].x = 1.0}, but not \nomatch{.x = 2.0}.
 AST_MATCHER_P(DesignatedInitExpr, designatorCountIs, unsigned, N) {
   return Node.size() == N;
 }
 
 /// Matches \c QualTypes in the clang AST.
+///
+/// Given
+/// \code
+///   int a = 0;
+///   const int b = 1;
+/// \endcode
+///
+/// The matcher \matcher{varDecl(hasType(qualType(isConstQualified())))}
+/// matches \match{const int b = 1}, but not \nomatch{int a = 0}.
 extern const internal::VariadicAllOfMatcher<QualType> qualType;
 
 /// Matches \c Types in the clang AST.
+///
+/// Given
+/// \code
+///   const int b = 1;
+/// \endcode
+///
+/// The matcher \matcher{varDecl(hasType(type().bind("type")))}
+/// matches \match{const int b = 1}, with \matcher{type=sub$type()}
+/// matching \match{sub=type$int}.
 extern const internal::VariadicAllOfMatcher<Type> type;
 
 /// Matches \c TypeLocs in the clang AST.
+///
+/// That is, information about a type and where it was written.
+///
+/// \code
+///   void foo(int val);
+/// \endcode
+///
+/// The matcher \matcher{declaratorDecl(hasTypeLoc(typeLoc().bind("type")))}
+/// matches \match{void foo(int val)} and \match{int val}, with
+/// \matcher{type=sub$typeLoc()} matching \match{sub=type$void} and
+/// \match{sub=type$int} respectively.
 extern const internal::VariadicAllOfMatcher<TypeLoc> typeLoc;
 
 /// Matches if any of the given matchers matches.
@@ -2801,18 +3793,20 @@ extern const internal::VariadicAllOfMatcher<TypeLoc> typeLoc;
 /// Unlike \c anyOf, \c eachOf will generate a match result for each
 /// matching submatcher.
 ///
-/// For example, in:
-/// \code
-///   class A { int a; int b; };
-/// \endcode
-/// The matcher:
+/// Given
 /// \code
-///   cxxRecordDecl(eachOf(has(fieldDecl(hasName("a")).bind("v")),
-///                        has(fieldDecl(hasName("b")).bind("v"))))
+///   void f(int a, int b);
 /// \endcode
-/// will generate two results binding "v", the first of which binds
-/// the field declaration of \c a, the second the field declaration of
-/// \c b.
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{functionDecl(hasAnyParameter(
+/// eachOf(parmVarDecl(hasName("a")).bind("v"),
+///        parmVarDecl(hasName("b")).bind("v"))))}
+/// matches \match{void f(int a, int b)},
+/// with \matcher{type=sub$parmVarDecl(hasName("a"))} matching \match{sub=v$a}
+/// for one match,
+/// and with \matcher{type=sub$parmVarDecl(hasName("b"))} matching
+/// \match{sub=v$b} for the other match.
 ///
 /// Usable as: Any Matcher
 extern const internal::VariadicOperatorMatcherFunc<
@@ -2822,6 +3816,15 @@ extern const internal::VariadicOperatorMatcherFunc<
 /// Matches if any of the given matchers matches.
 ///
 /// Usable as: Any Matcher
+///
+/// \code
+///   char v0 = 'a';
+///   int v1 = 1;
+///   float v2 = 2.0;
+/// \endcode
+///
+/// The matcher \matcher{varDecl(anyOf(hasName("v0"), hasType(isInteger())))}
+/// matches \match{char v0 = 'a'} and \match{int v1 = 1}.
 extern const internal::VariadicOperatorMatcherFunc<
     2, std::numeric_limits<unsigned>::max()>
     anyOf;
@@ -2829,6 +3832,14 @@ extern const internal::VariadicOperatorMatcherFunc<
 /// Matches if all given matchers match.
 ///
 /// Usable as: Any Matcher
+///
+/// \code
+///   int v0 = 0;
+///   int v1 = 1;
+/// \endcode
+///
+/// The matcher \matcher{varDecl(allOf(hasName("v0"), hasType(isInteger())))}
+/// matches \match{int v0 = 0}.
 extern const internal::VariadicOperatorMatcherFunc<
     2, std::numeric_limits<unsigned>::max()>
     allOf;
@@ -2839,22 +3850,14 @@ extern const internal::VariadicOperatorMatcherFunc<
 /// Useful when additional information which may or may not present about a main
 /// matching node is desired.
 ///
-/// For example, in:
-/// \code
-///   class Foo {
-///     int bar;
-///   }
-/// \endcode
-/// The matcher:
+/// Given
 /// \code
-///   cxxRecordDecl(
-///     optionally(has(
-///       fieldDecl(hasName("bar")).bind("var")
-///   ))).bind("record")
+///   int a = 0;
+///   int b;
 /// \endcode
-/// will produce a result binding for both "record" and "var".
-/// The matcher will produce a "record" binding for even if there is no data
-/// member named "bar" in that class.
+///
+/// The matcher \matcher{varDecl(optionally(hasInitializer(expr())))}
+/// matches \match{int a = 0} and \match{int b}.
 ///
 /// Usable as: Any Matcher
 extern const internal::VariadicOperatorMatcherFunc<1, 1> optionally;
@@ -2863,11 +3866,12 @@ extern const internal::VariadicOperatorMatcherFunc<1, 1> optionally;
 ///
 /// Given
 /// \code
-///   Foo x = bar;
+///   int x = 42;
 ///   int y = sizeof(x) + alignof(x);
 /// \endcode
-/// unaryExprOrTypeTraitExpr()
-///   matches \c sizeof(x) and \c alignof(x)
+/// \compile_args{-std=c++11-or-later,c23-or-later}
+/// The matcher \matcher{unaryExprOrTypeTraitExpr()}
+/// matches \match{sizeof(x)} and \match{alignof(x)}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt,
                                                    UnaryExprOrTypeTraitExpr>
     unaryExprOrTypeTraitExpr;
@@ -2876,26 +3880,26 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt,
 ///
 /// Given
 /// \code
-///   if (true);
-///   for (; true; );
-/// \endcode
-/// with the matcher
-/// \code
-///   mapAnyOf(ifStmt, forStmt).with(
-///     hasCondition(cxxBoolLiteralExpr(equals(true)))
-///     ).bind("trueCond")
-/// \endcode
-/// matches the \c if and the \c for. It is equivalent to:
-/// \code
-///   auto trueCond = hasCondition(cxxBoolLiteralExpr(equals(true)));
-///   anyOf(
-///     ifStmt(trueCond).bind("trueCond"),
-///     forStmt(trueCond).bind("trueCond")
-///     );
+///   void f() {
+///     if (true);
+///     for (; true; );
+///   }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+///
+/// The matcher \matcher{stmt(mapAnyOf(ifStmt, forStmt).with(
+///     hasCondition(cxxBoolLiteral(equals(true)))
+///     ))},
+/// which is equivalent to
+/// \matcher{stmt(anyOf(
+///     ifStmt(hasCondition(cxxBoolLiteral(equals(true)))).bind("trueCond"),
+///     forStmt(hasCondition(cxxBoolLiteral(equals(true)))).bind("trueCond")
+///     ))},
+/// matches \match{if (true);} and \match{for (; true; );}.
 ///
 /// The with() chain-call accepts zero or more matchers which are combined
 /// as-if with allOf() in each of the node matchers.
+///
 /// Usable as: Any Matcher
 template <typename T, typename... U>
 auto mapAnyOf(internal::VariadicDynCastAllOfMatcher<T, U> const &...) {
@@ -2904,34 +3908,23 @@ auto mapAnyOf(internal::VariadicDynCastAllOfMatcher<T, U> const &...) {
 
 /// Matches nodes which can be used with binary operators.
 ///
-/// The code
-/// \code
-///   var1 != var2;
-/// \endcode
-/// might be represented in the clang AST as a binaryOperator, a
-/// cxxOperatorCallExpr or a cxxRewrittenBinaryOperator, depending on
+/// A comparison of two expressions might be represented in the clang AST as a
+/// \c binaryOperator, a \c cxxOperatorCallExpr or a
+/// \c cxxRewrittenBinaryOperator, depending on
 ///
 /// * whether the types of var1 and var2 are fundamental (binaryOperator) or at
-///   least one is a class type (cxxOperatorCallExpr)
+///   least one is a class type (\c cxxOperatorCallExpr)
 /// * whether the code appears in a template declaration, if at least one of the
-///   vars is a dependent-type (binaryOperator)
+///   vars is a dependent-type (\c binaryOperator)
 /// * whether the code relies on a rewritten binary operator, such as a
 /// spaceship operator or an inverted equality operator
-/// (cxxRewrittenBinaryOperator)
+/// (\c cxxRewrittenBinaryOperator)
 ///
 /// This matcher elides details in places where the matchers for the nodes are
 /// compatible.
 ///
 /// Given
 /// \code
-///   binaryOperation(
-///     hasOperatorName("!="),
-///     hasLHS(expr().bind("lhs")),
-///     hasRHS(expr().bind("rhs"))
-///   )
-/// \endcode
-/// matches each use of "!=" in:
-/// \code
 ///   struct S{
 ///       bool operator!=(const S&) const;
 ///   };
@@ -2945,25 +3938,28 @@ auto mapAnyOf(internal::VariadicDynCastAllOfMatcher<T, U> const &...) {
 ///   template<typename T>
 ///   void templ()
 ///   {
-///      1 != 2;
+///      3 != 4;
 ///      T() != S();
 ///   }
 ///   struct HasOpEq
 ///   {
-///       bool operator==(const HasOpEq &) const;
+///       friend bool
+///       operator==(const HasOpEq &, const HasOpEq&) noexcept = default;
 ///   };
 ///
 ///   void inverse()
 ///   {
-///       HasOpEq s1;
-///       HasOpEq s2;
-///       if (s1 != s2)
+///       HasOpEq e1;
+///       HasOpEq e2;
+///       if (e1 != e2)
 ///           return;
 ///   }
 ///
 ///   struct HasSpaceship
 ///   {
-///       bool operator<=>(const HasOpEq &) const;
+///       friend bool
+///       operator<=>(const HasSpaceship &,
+///                   const HasSpaceship&) noexcept = default;
 ///   };
 ///
 ///   void use_spaceship()
@@ -2974,18 +3970,27 @@ auto mapAnyOf(internal::VariadicDynCastAllOfMatcher<T, U> const &...) {
 ///           return;
 ///   }
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++20-or-later}
+///
+/// The matcher \matcher{binaryOperation(
+///     hasOperatorName("!="),
+///     hasLHS(expr().bind("lhs")),
+///     hasRHS(expr().bind("rhs"))
+///   )}
+/// matches \match{1 != 2}, \match{S() != S()}, \match{3 != 4},
+/// \match{T() != S()}, \match{e1 != e2} and \match{s1 != s2}.
 extern const internal::MapAnyOfMatcher<BinaryOperator, CXXOperatorCallExpr,
                                        CXXRewrittenBinaryOperator>
     binaryOperation;
 
 /// Matches function calls and constructor calls
 ///
-/// Because CallExpr and CXXConstructExpr do not share a common
+/// Because \c CallExpr and \c CXXConstructExpr do not share a common
 /// base class with API accessing arguments etc, AST Matchers for code
 /// which should match both are typically duplicated. This matcher
 /// removes the need for duplication.
 ///
-/// Given code
+/// Given
 /// \code
 /// struct ConstructorTakesInt
 /// {
@@ -3006,12 +4011,12 @@ extern const internal::MapAnyOfMatcher<BinaryOperator, CXXOperatorCallExpr,
 ///   ConstructorTakesInt cti(42);
 /// }
 /// \endcode
+/// \compile_args{-std=c++}
 ///
 /// The matcher
-/// \code
-/// invocation(hasArgument(0, integerLiteral(equals(42))))
-/// \endcode
-/// matches the expression in both doCall and doConstruct
+/// \matcher{expr(invocation(hasArgument(0, integerLiteral(equals(42)))))}
+/// matches the expressions \match{callTakesInt(42)}
+/// and \match{cti(42)}.
 extern const internal::MapAnyOfMatcher<CallExpr, CXXConstructExpr> invocation;
 
 /// Matches unary expressions that have a specific type of argument.
@@ -3020,8 +4025,10 @@ extern const internal::MapAnyOfMatcher<CallExpr, CXXConstructExpr> invocation;
 /// \code
 ///   int a, c; float b; int s = sizeof(a) + sizeof(b) + alignof(c);
 /// \endcode
-/// unaryExprOrTypeTraitExpr(hasArgumentOfType(asString("int"))
-///   matches \c sizeof(a) and \c alignof(c)
+/// \compile_args{-std=c++11-or-later,c23-or-later}
+/// The matcher
+/// \matcher{unaryExprOrTypeTraitExpr(hasArgumentOfType(asString("int")))}
+/// matches \match{sizeof(a)} and \match{alignof(c)}
 AST_MATCHER_P(UnaryExprOrTypeTraitExpr, hasArgumentOfType,
               internal::Matcher<QualType>, InnerMatcher) {
   const QualType ArgumentType = Node.getTypeOfArgument();
@@ -3033,10 +4040,11 @@ AST_MATCHER_P(UnaryExprOrTypeTraitExpr, hasArgumentOfType,
 /// Given
 /// \code
 ///   int x;
-///   int s = sizeof(x) + alignof(x)
+///   int s = sizeof(x) + alignof(x);
 /// \endcode
-/// unaryExprOrTypeTraitExpr(ofKind(UETT_SizeOf))
-///   matches \c sizeof(x)
+/// \compile_args{-std=c++11-or-later,c23-or-later}
+/// The matcher \matcher{unaryExprOrTypeTraitExpr(ofKind(UETT_SizeOf))}
+/// matches \match{sizeof(x)}
 ///
 /// If the matcher is use from clang-query, UnaryExprOrTypeTrait parameter
 /// should be passed as a quoted string. e.g., ofKind("UETT_SizeOf").
@@ -3046,8 +4054,17 @@ AST_MATCHER_P(UnaryExprOrTypeTraitExpr, ofKind, UnaryExprOrTypeTrait, Kind) {
 
 /// Same as unaryExprOrTypeTraitExpr, but only matching
 /// alignof.
-inline internal::BindableMatcher<Stmt> alignOfExpr(
-    const internal::Matcher<UnaryExprOrTypeTraitExpr> &InnerMatcher) {
+///
+/// Given
+/// \code
+///   int align = alignof(int);
+/// \endcode
+/// \compile_args{-std=c++11-or-later,c23-or-later}
+///
+/// The matcher \matcher{alignOfExpr(expr())}
+/// matches \match{alignof(int)}.
+inline internal::BindableMatcher<Stmt>
+alignOfExpr(const internal::Matcher<UnaryExprOrTypeTraitExpr> &InnerMatcher) {
   return stmt(unaryExprOrTypeTraitExpr(
       allOf(anyOf(ofKind(UETT_AlignOf), ofKind(UETT_PreferredAlignOf)),
             InnerMatcher)));
@@ -3055,6 +4072,15 @@ inline internal::BindableMatcher<Stmt> alignOfExpr(
 
 /// Same as unaryExprOrTypeTraitExpr, but only matching
 /// sizeof.
+///
+/// Given
+/// \code
+///   struct S { double x; double y; };
+///   int size = sizeof(struct S);
+/// \endcode
+///
+/// The matcher \matcher{sizeOfExpr(expr())}
+/// matches \match{sizeof(struct S)}.
 inline internal::BindableMatcher<Stmt> sizeOfExpr(
     const internal::Matcher<UnaryExprOrTypeTraitExpr> &InnerMatcher) {
   return stmt(unaryExprOrTypeTraitExpr(
@@ -3067,15 +4093,26 @@ inline internal::BindableMatcher<Stmt> sizeOfExpr(
 /// with '<enclosing>::'.
 /// Does not match typedefs of an underlying type with the given name.
 ///
-/// Example matches X (Name == "X")
+/// Given
 /// \code
 ///   class X;
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{namedDecl(hasName("X"))}
+/// matches \match{class X}.
 ///
-/// Example matches X (Name is one of "::a::b::X", "a::b::X", "b::X", "X")
+/// Given
 /// \code
 ///   namespace a { namespace b { class X; } }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matchers \matcher{namedDecl(hasName("::a::b::X"))},
+/// \matcher{namedDecl(hasName("a::b::X"))},
+/// \matcher{namedDecl(hasName("b::X"))} and
+/// \matcher{namedDecl(hasName("X"))}
+/// match \match{class X}.
 inline internal::Matcher<NamedDecl> hasName(StringRef Name) {
   return internal::Matcher<NamedDecl>(
       new internal::HasNameMatcher({std::string(Name)}));
@@ -3084,13 +4121,17 @@ inline internal::Matcher<NamedDecl> hasName(StringRef Name) {
 /// Matches NamedDecl nodes that have any of the specified names.
 ///
 /// This matcher is only provided as a performance optimization of hasName.
+///
+/// Given
 /// \code
-///     hasAnyName(a, b, c)
-/// \endcode
-///  is equivalent to, but faster than
-/// \code
-///     anyOf(hasName(a), hasName(b), hasName(c))
+///   void f(int a, int b);
 /// \endcode
+///
+/// The matcher \matcher{namedDecl(hasAnyName("a", "b"))},
+/// which is equivalent to the matcher
+/// \matcher{namedDecl(hasAnyName("a", "b"))},
+/// matches \match{int a} and \match{int b}, but not
+/// \nomatch{void f(int a, int b)}.
 extern const internal::VariadicFunction<internal::Matcher<NamedDecl>, StringRef,
                                         internal::hasAnyNameFunc>
     hasAnyName;
@@ -3102,15 +4143,14 @@ extern const internal::VariadicFunction<internal::Matcher<NamedDecl>, StringRef,
 /// prefixing the name with '<enclosing>::'.  Does not match typedefs
 /// of an underlying type with the given name.
 ///
-/// Example matches X (regexp == "::X")
-/// \code
-///   class X;
-/// \endcode
-///
-/// Example matches X (regexp is one of "::X", "^foo::.*X", among others)
+/// Given
 /// \code
 ///   namespace foo { namespace bar { class X; } }
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{namedDecl(matchesName("^::foo:.*X"))}
+/// matches \match{class X}.
 AST_MATCHER_REGEX(NamedDecl, matchesName, RegExp) {
   std::string FullNameString = "::" + Node.getQualifiedNameAsString();
   return RegExp->match(FullNameString);
@@ -3121,18 +4161,21 @@ AST_MATCHER_REGEX(NamedDecl, matchesName, RegExp) {
 /// Matches overloaded operator names specified in strings without the
 /// "operator" prefix: e.g. "<<".
 ///
-/// Given:
+/// Given
 /// \code
-///   class A { int operator*(); };
+///   struct A { int operator*(); };
 ///   const A &operator<<(const A &a, const A &b);
-///   A a;
-///   a << a;   // <-- This matches
+///   void f(A a) {
+///     a << a;   // <-- This matches
+///   }
 /// \endcode
+/// \compile_args{-std=c++}
 ///
-/// \c cxxOperatorCallExpr(hasOverloadedOperatorName("<<"))) matches the
-/// specified line and
-/// \c cxxRecordDecl(hasMethod(hasOverloadedOperatorName("*")))
-/// matches the declaration of \c A.
+/// The matcher \matcher{cxxOperatorCallExpr(hasOverloadedOperatorName("<<"))}
+/// matches \match{a << a}.
+/// The matcher
+/// \matcher{cxxRecordDecl(hasMethod(hasOverloadedOperatorName("*")))}
+/// matches \match{struct A { int operator*(); }}.
 ///
 /// Usable as: Matcher<CXXOperatorCallExpr>, Matcher<FunctionDecl>
 inline internal::PolymorphicMatcher<
@@ -3152,6 +4195,32 @@ hasOverloadedOperatorName(StringRef Name) {
 /// "operator" prefix: e.g. "<<".
 ///
 ///   hasAnyOverloadedOperatorName("+", "-")
+///
+/// Given
+/// \code
+///   struct Point { double x; double y; };
+///   Point operator+(const Point&, const Point&);
+///   Point operator-(const Point&, const Point&);
+///
+///   Point sub(Point a, Point b) {
+///     return b - a;
+///   }
+/// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{functionDecl(hasAnyOverloadedOperatorName("+", "-"))},
+/// which is equivalent to
+/// \matcher{functionDecl(anyOf(hasAnyOverloadedOperatorName("+"),
+/// hasOverloadedOperatorName("-")))},
+/// matches \match{Point operator+(const Point&, const Point&)} and
+/// \match{Point operator-(const Point&, const Point&)}.
+/// The matcher
+/// \matcher{cxxOperatorCallExpr(hasAnyOverloadedOperatorName("+", "-"))},
+/// which is equivalent to
+/// \matcher{cxxOperatorCallExpr(anyOf(hasOverloadedOperatorName("+"),
+/// hasOverloadedOperatorName("-")))},
+/// matches \match{b - a}.
+///
 /// Is equivalent to
 ///   anyOf(hasOverloadedOperatorName("+"), hasOverloadedOperatorName("-"))
 extern const internal::VariadicFunction<
@@ -3181,7 +4250,9 @@ extern const internal::VariadicFunction<
 ///       s.mem();
 ///   }
 /// \endcode
-/// \c cxxDependentScopeMemberExpr(hasMemberName("mem")) matches `s.mem()`
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{cxxDependentScopeMemberExpr(hasMemberName("mem"))}
+/// matches \match{s.mem}.
 AST_MATCHER_P(CXXDependentScopeMemberExpr, hasMemberName, std::string, N) {
   return Node.getMember().getAsString() == N;
 }
@@ -3207,19 +4278,20 @@ AST_MATCHER_P(CXXDependentScopeMemberExpr, hasMemberName, std::string, N) {
 ///       s.mem();
 ///   }
 /// \endcode
-/// The matcher
-/// @code
-/// \c cxxDependentScopeMemberExpr(
-///   hasObjectExpression(declRefExpr(hasType(templateSpecializationType(
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{cxxDependentScopeMemberExpr(
+///   hasObjectExpression(declRefExpr(hasType(
+///     elaboratedType(namesType(templateSpecializationType(
 ///       hasDeclaration(classTemplateDecl(has(cxxRecordDecl(has(
 ///           cxxMethodDecl(hasName("mem")).bind("templMem")
 ///           )))))
-///       )))),
+///     )))
+///   ))),
 ///   memberHasSameNameAsBoundNode("templMem")
-///   )
-/// @endcode
-/// first matches and binds the @c mem member of the @c S template, then
-/// compares its name to the usage in @c s.mem() in the @c x function template
+/// )}
+/// matches \match{s.mem}, with the inner matcher
+/// \matcher{type=sub$cxxMethodDecl(hasName("mem"))} matching
+/// \match{sub=templMem$void mem()} of the \c S template.
 AST_MATCHER_P(CXXDependentScopeMemberExpr, memberHasSameNameAsBoundNode,
               std::string, BindingID) {
   auto MemberName = Node.getMember().getAsString();
@@ -3244,26 +4316,31 @@ AST_MATCHER_P(CXXDependentScopeMemberExpr, memberHasSameNameAsBoundNode,
 ///
 /// Example matches Y, Z, C (Base == hasName("X"))
 /// \code
-///   class X;
+///   class X {};
 ///   class Y : public X {};  // directly derived
 ///   class Z : public Y {};  // indirectly derived
 ///   typedef X A;
 ///   typedef A B;
 ///   class C : public B {};  // derived from a typedef of X
-/// \endcode
 ///
-/// In the following example, Bar matches isDerivedFrom(hasName("X")):
-/// \code
-///   class Foo;
-///   typedef Foo X;
-///   class Bar : public Foo {};  // derived from a type that X is a typedef of
+///   class Foo {};
+///   typedef Foo Alias;
+///   class Bar : public Alias {};
+///   // derived from a type that Alias is a typedef of Foo
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxRecordDecl(isDerivedFrom(hasName("X")))}
+/// matches \match{type=name$Y}, \match{type=name$Z} and \match{type=name$C}.
+/// The matcher \matcher{cxxRecordDecl(isDerivedFrom(hasName("Foo")))}
+/// matches \match{type=name$Bar}.
 ///
 /// In the following example, Bar matches isDerivedFrom(hasName("NSObject"))
 /// \code
 ///   @interface NSObject @end
 ///   @interface Bar : NSObject @end
 /// \endcode
+/// \compile_args{-ObjC}
 ///
 /// Usable as: Matcher<CXXRecordDecl>, Matcher<ObjCInterfaceDecl>
 AST_POLYMORPHIC_MATCHER_P(
@@ -3281,6 +4358,42 @@ AST_POLYMORPHIC_MATCHER_P(
 }
 
 /// Overloaded method as shortcut for \c isDerivedFrom(hasName(...)).
+///
+/// Matches C++ classes that are directly or indirectly derived from a class
+/// matching \c Base, or Objective-C classes that directly or indirectly
+/// subclass a class matching \c Base.
+///
+/// Note that a class is not considered to be derived from itself.
+///
+/// Example matches Y, Z, C (Base == hasName("X"))
+/// \code
+///   class X {};
+///   class Y : public X {};  // directly derived
+///   class Z : public Y {};  // indirectly derived
+///   typedef X A;
+///   typedef A B;
+///   class C : public B {};  // derived from a typedef of X
+///
+///   class Foo {};
+///   typedef Foo Alias;
+///   class Bar : public Alias {};  // derived from Alias, which is a
+///                                 // typedef of Foo
+/// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxRecordDecl(isDerivedFrom("X"))}
+/// matches \match{type=name$Y}, \match{type=name$Z} and \match{type=name$C}.
+/// The matcher \matcher{cxxRecordDecl(isDerivedFrom("Foo"))}
+/// matches \match{type=name$Bar}.
+///
+/// In the following example, Bar matches isDerivedFrom(hasName("NSObject"))
+/// \code
+///   @interface NSObject @end
+///   @interface Bar : NSObject @end
+/// \endcode
+/// \compile_args{-ObjC}
+///
+/// Usable as: Matcher<CXXRecordDecl>, Matcher<ObjCInterfaceDecl>
 AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
     isDerivedFrom,
     AST_POLYMORPHIC_SUPPORTED_TYPES(CXXRecordDecl, ObjCInterfaceDecl),
@@ -3300,17 +4413,20 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
 /// Matches C++ classes that have a direct or indirect base matching \p
 /// BaseSpecMatcher.
 ///
-/// Example:
-/// matcher hasAnyBase(hasType(cxxRecordDecl(hasName("SpecialBase"))))
+/// Given
 /// \code
-///   class Foo;
+///   class Foo {};
 ///   class Bar : Foo {};
 ///   class Baz : Bar {};
-///   class SpecialBase;
+///   class SpecialBase {};
 ///   class Proxy : SpecialBase {};  // matches Proxy
 ///   class IndirectlyDerived : Proxy {};  //matches IndirectlyDerived
 /// \endcode
+/// \compile_args{-std=c++}
 ///
+/// The matcher
+/// \matcher{cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("SpecialBase")))))}
+/// matches \match{type=name$Proxy} and \match{type=name$IndirectlyDerived}
 // FIXME: Refactor this and isDerivedFrom to reuse implementation.
 AST_MATCHER_P(CXXRecordDecl, hasAnyBase, internal::Matcher<CXXBaseSpecifier>,
               BaseSpecMatcher) {
@@ -3319,16 +4435,19 @@ AST_MATCHER_P(CXXRecordDecl, hasAnyBase, internal::Matcher<CXXBaseSpecifier>,
 
 /// Matches C++ classes that have a direct base matching \p BaseSpecMatcher.
 ///
-/// Example:
-/// matcher hasDirectBase(hasType(cxxRecordDecl(hasName("SpecialBase"))))
+/// Given
 /// \code
-///   class Foo;
+///   class Foo {};
 ///   class Bar : Foo {};
 ///   class Baz : Bar {};
-///   class SpecialBase;
+///   class SpecialBase {};
 ///   class Proxy : SpecialBase {};  // matches Proxy
 ///   class IndirectlyDerived : Proxy {};  // doesn't match
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(hasDirectBase(hasType(cxxRecordDecl(hasName("SpecialBase")))))}
+/// matches \match{type=name$Proxy}
 AST_MATCHER_P(CXXRecordDecl, hasDirectBase, internal::Matcher<CXXBaseSpecifier>,
               BaseSpecMatcher) {
   return Node.hasDefinition() &&
@@ -3339,6 +4458,22 @@ AST_MATCHER_P(CXXRecordDecl, hasDirectBase, internal::Matcher<CXXBaseSpecifier>,
 
 /// Similar to \c isDerivedFrom(), but also matches classes that directly
 /// match \c Base.
+///
+/// Given
+/// \code
+///   class X {};
+///   class Y : public X {};  // directly derived
+///   class Z : public Y {};  // indirectly derived
+///   typedef X A;
+///   typedef A B;
+///   class C : public B {};  // derived from a typedef of X
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(isSameOrDerivedFrom(cxxRecordDecl(hasName("X"))),
+/// isDefinition())}
+/// matches \match{class X {}}, \match{class Y : public X {}},
+/// \match{class Z : public Y {}} and \match{class C : public B {}}.
 AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
     isSameOrDerivedFrom,
     AST_POLYMORPHIC_SUPPORTED_TYPES(CXXRecordDecl, ObjCInterfaceDecl),
@@ -3352,8 +4487,25 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
   return Matcher<ObjCInterfaceDecl>(M).matches(*InterfaceDecl, Finder, Builder);
 }
 
+/// Similar to \c isDerivedFrom(), but also matches classes that directly
+/// match \c Base.
 /// Overloaded method as shortcut for
 /// \c isSameOrDerivedFrom(hasName(...)).
+///
+/// Given
+/// \code
+///   class X {};
+///   class Y : public X {};  // directly derived
+///   class Z : public Y {};  // indirectly derived
+///   typedef X A;
+///   typedef A B;
+///   class C : public B {};  // derived from a typedef of X
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(isSameOrDerivedFrom("X"), isDefinition())}
+/// matches \match{class X {}}, \match{class Y : public X {}},
+/// \match{class Z : public Y {}} and \match{class C : public B {}}.
 AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
     isSameOrDerivedFrom,
     AST_POLYMORPHIC_SUPPORTED_TYPES(CXXRecordDecl, ObjCInterfaceDecl),
@@ -3375,22 +4527,29 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
 ///
 /// Note that a class is not considered to be derived from itself.
 ///
-/// Example matches Y, C (Base == hasName("X"))
+/// Given
 /// \code
-///   class X;
+///   class X {};
 ///   class Y : public X {};  // directly derived
 ///   class Z : public Y {};  // indirectly derived
 ///   typedef X A;
 ///   typedef A B;
 ///   class C : public B {};  // derived from a typedef of X
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(isDirectlyDerivedFrom(namedDecl(hasName("X"))))}
+/// matches \match{type=name$Y} and \match{type=name$C} (Base == hasName("X")
 ///
 /// In the following example, Bar matches isDerivedFrom(hasName("X")):
 /// \code
-///   class Foo;
+///   class Foo {};
 ///   typedef Foo X;
 ///   class Bar : public Foo {};  // derived from a type that X is a typedef of
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(isDerivedFrom(hasName("X")))}
+/// matches \match{type=name$Bar}
 AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
     isDirectlyDerivedFrom,
     AST_POLYMORPHIC_SUPPORTED_TYPES(CXXRecordDecl, ObjCInterfaceDecl),
@@ -3406,6 +4565,18 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
 }
 
 /// Overloaded method as shortcut for \c isDirectlyDerivedFrom(hasName(...)).
+///
+/// Given
+/// \code
+///   struct Base {};
+///   struct DirectlyDerived : public Base {};
+///   struct IndirectlyDerived : public DirectlyDerived {};
+/// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{cxxRecordDecl(isDirectlyDerivedFrom("Base"))}
+/// matches \match{type=name$DirectlyDerived}, but not
+/// \nomatch{type=name$IndirectlyDerived}.
 AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
     isDirectlyDerivedFrom,
     AST_POLYMORPHIC_SUPPORTED_TYPES(CXXRecordDecl, ObjCInterfaceDecl),
@@ -3423,14 +4594,16 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
 /// Matches the first method of a class or struct that satisfies \c
 /// InnerMatcher.
 ///
-/// Given:
+/// Given
 /// \code
 ///   class A { void func(); };
 ///   class B { void member(); };
 /// \endcode
+/// \compile_args{-std=c++}
 ///
-/// \c cxxRecordDecl(hasMethod(hasName("func"))) matches the declaration of
-/// \c A but not \c B.
+/// The matcher \matcher{cxxRecordDecl(hasMethod(hasName("func")))}
+/// matches the declaration of \match{class A { void func(); }}
+/// but does not match \nomatch{class B { void member(); }}
 AST_MATCHER_P(CXXRecordDecl, hasMethod, internal::Matcher<CXXMethodDecl>,
               InnerMatcher) {
   BoundNodesTreeBuilder Result(*Builder);
@@ -3447,13 +4620,14 @@ AST_MATCHER_P(CXXRecordDecl, hasMethod, internal::Matcher<CXXMethodDecl>,
 
 /// Matches the generated class of lambda expressions.
 ///
-/// Given:
+/// Given
 /// \code
 ///   auto x = []{};
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// \c cxxRecordDecl(isLambda()) matches the implicit class declaration of
-/// \c decltype(x)
+/// The matcher \matcher{varDecl(hasType(cxxRecordDecl(isLambda())))}
+/// matches \match{auto x = []{}}.
 AST_MATCHER(CXXRecordDecl, isLambda) {
   return Node.isLambda();
 }
@@ -3461,33 +4635,49 @@ AST_MATCHER(CXXRecordDecl, isLambda) {
 /// Matches AST nodes that have child AST nodes that match the
 /// provided matcher.
 ///
-/// Example matches X, Y
-///   (matcher = cxxRecordDecl(has(cxxRecordDecl(hasName("X")))
+/// Given
 /// \code
 ///   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.
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(has(cxxRecordDecl(hasName("X"))))}
+/// matches \match{count=3$class X {}} three times,
+/// and \match{count=2$class Y { class X {}; }} two times.
 ///
 /// ChildT must be an AST base type.
 ///
 /// Usable as: Any Matcher
 /// Note that has is direct matcher, so it also matches things like implicit
 /// casts and paren casts. If you are matching with expr then you should
-/// probably consider using ignoringParenImpCasts like:
-/// has(ignoringParenImpCasts(expr())).
+/// probably consider using ignoringParenImpCasts:
+///
+/// Given
+/// \code
+///   int x =0;
+///   double y = static_cast<double>(x);
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxStaticCastExpr(has(ignoringParenImpCasts(declRefExpr())))}.
+/// matches \match{static_cast<double>(x)}
 extern const internal::ArgumentAdaptingMatcherFunc<internal::HasMatcher> has;
 
 /// Matches AST nodes that have descendant AST nodes that match the
 /// provided matcher.
 ///
-/// Example matches X, Y, Z
-///     (matcher = cxxRecordDecl(hasDescendant(cxxRecordDecl(hasName("X")))))
+/// Given
 /// \code
 ///   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 {}; }; };
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(hasDescendant(cxxRecordDecl(hasName("X"))))}
+/// matches \match{count=3$class X {}}, \match{count=2$class Y { class X {}; }}
+/// and \match{class Z { class Y { class X {}; }; }}.
 ///
 /// DescendantT must be an AST base type.
 ///
@@ -3499,19 +4689,24 @@ extern const internal::ArgumentAdaptingMatcherFunc<
 /// Matches AST nodes that have child AST nodes that match the
 /// provided matcher.
 ///
-/// Example matches X, Y, Y::X, Z::Y, Z::Y::X
-///   (matcher = cxxRecordDecl(forEach(cxxRecordDecl(hasName("X")))
+/// Given
 /// \code
 ///   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
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(forEach(cxxRecordDecl(hasName("X"))))}
+/// matches \match{type=typestr$class X},
+/// \match{type=typestr$class Y},
+/// \match{type=typestr$class Y::X},
+/// \match{type=typestr$class Z::Y::X} and \match{type=typestr$class Z::Y}
 ///
 /// 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.
+///   matches instead of only on the first one.
 ///
 /// Usable as: Any Matcher
 extern const internal::ArgumentAdaptingMatcherFunc<internal::ForEachMatcher>
@@ -3520,14 +4715,19 @@ extern const internal::ArgumentAdaptingMatcherFunc<internal::ForEachMatcher>
 /// Matches AST nodes that have descendant AST nodes that match the
 /// provided matcher.
 ///
-/// Example matches X, A, A::X, B, B::C, B::C::X
-///   (matcher = cxxRecordDecl(forEachDescendant(cxxRecordDecl(hasName("X")))))
+/// Given
 /// \code
 ///   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
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(forEachDescendant(cxxRecordDecl(hasName("X"))))}
+/// matches \match{type=name;count=2$X}, \match{type=name$A},
+/// \match{type=name$B}, \match{type=typestr$class B::C}
+/// and \match{type=typestr$class B::C::X}
 ///
 /// DescendantT must be an AST base type.
 ///
@@ -3535,13 +4735,55 @@ extern const internal::ArgumentAdaptingMatcherFunc<internal::ForEachMatcher>
 /// 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:
 /// \code
-///   class A { class B { class C { class D { class E {}; }; }; }; };
+///   struct A {
+///     struct B {
+///       struct C {};
+///       struct D {};
+///     };
+///   };
+///
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(forEachDescendant(cxxRecordDecl(
+///     forEachDescendant(cxxRecordDecl().bind("inner"))
+///   ).bind("middle")))}
+/// will match 9 times:
+/// It matches the definition of \match{type=name$A} with the definition of
+/// \match{sub=middle;type=name$B} in the middle and the injected class name of
+/// \match{sub=inner;type=name$B} as the innermost \c cxxRecordDecl.
+///
+/// It matches the definition of \match{type=name$A} with the definition of
+/// \match{sub=middle;type=name$C} in the middle and the definition of
+/// \match{sub=inner;type=name$B} as the innermost \c cxxRecordDecl.
+///
+/// It matches the definition of \match{type=name$A} with the definition of
+/// \match{sub=middle;type=name$C} in the middle and the injected class name of
+/// \match{sub=inner;type=name$B} as the innermost \c cxxRecordDecl.
+///
+/// It matches the definition of \match{type=name$A} with the definition of
+/// \match{sub=middle;type=name$B} in the middle and the definition of
+/// \match{sub=inner;type=name$D} as the innermost \c cxxRecordDecl.
+///
+/// It matches the definition of \match{type=name$A} with the definition of
+/// \match{sub=middle;type=name$B} in the middle and the injected class name of
+/// \match{sub=inner;type=name$D} as the innermost \c cxxRecordDecl.
+///
+/// It matches the definition of \match{type=name$A} with the definition of
+/// \match{sub=middle;type=name$C} in the middle and the injected class name of
+/// \match{sub=inner;type=name$C} as the innermost \c cxxRecordDecl.
+///
+/// It matches the definition of \match{type=name$A} with the definition of
+/// \match{sub=middle;type=name$D} in the middle and the injected class name of
+/// \match{sub=inner;type=name$D} as the innermost \c cxxRecordDecl.
+///
+/// It matches the definition of \match{type=name$B} with the definition of
+/// \match{sub=middle;type=name$C} in the middle and the injected class name of
+/// \match{sub=inner;type=name$C} as the innermost \c cxxRecordDecl.
+///
+/// It matches the definition of \match{type=name$B} with the definition of
+/// \match{sub=middle;type=name$D} in the middle and the injected class name of
+/// \match{sub=inner;type=name$D} as the innermost \c cxxRecordDecl.
 ///
 /// Usable as: Any Matcher
 extern const internal::ArgumentAdaptingMatcherFunc<
@@ -3556,12 +4798,14 @@ extern const internal::ArgumentAdaptingMatcherFunc<
 /// \code
 ///   class A { class B {}; class C {}; };
 /// \endcode
-/// The matcher:
-/// \code
-///   cxxRecordDecl(hasName("::A"),
-///                 findAll(cxxRecordDecl(isDefinition()).bind("m")))
-/// \endcode
-/// will generate results for \c A, \c B and \c C.
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(hasName("::A"),
+///                 findAll(cxxRecordDecl(isDefinition()).bind("m")))}
+/// matches \match{type=name;count=3$A} three times,
+/// with \matcher{type=sub$cxxRecordDecl(isDefinition()).bind("m")}
+/// matching \match{type=name;sub=m$A},
+/// \match{type=name;sub=m$B} and \match{type=name;sub=m$C}.
 ///
 /// Usable as: Any Matcher
 template <typename T>
@@ -3576,7 +4820,9 @@ internal::Matcher<T> findAll(const internal::Matcher<T> &Matcher) {
 /// \code
 /// void f() { for (;;) { int x = 42; if (true) { int x = 43; } } }
 /// \endcode
-/// \c compoundStmt(hasParent(ifStmt())) matches "{ int x = 43; }".
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{compoundStmt(hasParent(ifStmt()))}
+/// matches \match{{ int x = 43; }}
 ///
 /// Usable as: Any Matcher
 extern const internal::ArgumentAdaptingMatcherFunc<
@@ -3593,7 +4839,10 @@ extern const internal::ArgumentAdaptingMatcherFunc<
 /// void f() { if (true) { int x = 42; } }
 /// void g() { for (;;) { int x = 43; } }
 /// \endcode
-/// \c expr(integerLiteral(hasAncestor(ifStmt()))) matches \c 42, but not 43.
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{expr(integerLiteral(hasAncestor(ifStmt())))}
+/// matches \match{42}
+/// but does not match \nomatch{43}
 ///
 /// Usable as: Any Matcher
 extern const internal::ArgumentAdaptingMatcherFunc<
@@ -3604,17 +4853,20 @@ extern const internal::ArgumentAdaptingMatcherFunc<
 
 /// Matches if the provided matcher does not match.
 ///
-/// Example matches Y (matcher = cxxRecordDecl(unless(hasName("X"))))
+/// Given
 /// \code
 ///   class X {};
 ///   class Y {};
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(unless(hasName("X")))}
+/// matches \match{type=name;count=2$Y}
 ///
 /// Usable as: Any Matcher
 extern const internal::VariadicOperatorMatcherFunc<1, 1> unless;
 
 /// Matches a node if the declaration associated with that node
-/// matches the given matcher.
+///   matches the given matcher.
 ///
 /// The associated declaration is:
 /// - for type nodes, the declaration of the underlying type
@@ -3624,21 +4876,27 @@ extern const internal::VariadicOperatorMatcherFunc<1, 1> unless;
 /// - for CXXNewExpr, the declaration of the operator new
 /// - for ObjCIvarExpr, the declaration of the ivar
 ///
-/// For type nodes, hasDeclaration will generally match the declaration of the
-/// sugared type. Given
+/// Given
 /// \code
 ///   class X {};
 ///   typedef X Y;
 ///   Y y;
 /// \endcode
-/// in varDecl(hasType(hasDeclaration(decl()))) the decl will match the
-/// typedefDecl. A common use case is to match the underlying, desugared type.
+/// \compile_args{-std=c++}
+/// For type nodes, hasDeclaration will generally match the declaration of the
+/// sugared type, i.e., the matcher
+/// \matcher{varDecl(hasType(qualType(hasDeclaration(decl().bind("d")))))},
+/// matches \match{Y y}, with
+/// the matcher \matcher{type=sub$decl()} matching
+/// \match{sub=d$typedef X Y;}.
+/// A common use case is to match the underlying, desugared type.
 /// This can be achieved by using the hasUnqualifiedDesugaredType matcher:
-/// \code
-///   varDecl(hasType(hasUnqualifiedDesugaredType(
-///       recordType(hasDeclaration(decl())))))
-/// \endcode
-/// In this matcher, the decl will match the CXXRecordDecl of class X.
+/// \matcher{varDecl(hasType(hasUnqualifiedDesugaredType(
+///       recordType(hasDeclaration(decl().bind("d"))))))}
+/// matches \match{Y y}.
+/// In this matcher, the matcher \matcher{type=sub$decl()} will match the
+/// CXXRecordDecl
+/// \match{sub=d$class X {};}.
 ///
 /// Usable as: Matcher<AddrLabelExpr>, Matcher<CallExpr>,
 ///   Matcher<CXXConstructExpr>, Matcher<CXXNewExpr>, Matcher<DeclRefExpr>,
@@ -3665,9 +4923,10 @@ hasDeclaration(const internal::Matcher<Decl> &InnerMatcher) {
 ///   namespace N { template<class T> void f(T t); }
 ///   template <class T> void g() { using N::f; f(T()); }
 /// \endcode
-/// \c unresolvedLookupExpr(hasAnyDeclaration(
-///     namedDecl(hasUnderlyingDecl(hasName("::N::f")))))
-///   matches the use of \c f in \c g() .
+/// \compile_args{-fno-delayed-template-parsing;-std=c++11-or-later}
+/// The matcher \matcher{unresolvedLookupExpr(hasAnyDeclaration(
+///     namedDecl(hasUnderlyingDecl(hasName("::N::f")))))}
+///   matches \match{f} in \c g().
 AST_MATCHER_P(NamedDecl, hasUnderlyingDecl, internal::Matcher<NamedDecl>,
               InnerMatcher) {
   const NamedDecl *UnderlyingDecl = Node.getUnderlyingDecl();
@@ -3686,12 +4945,15 @@ AST_MATCHER_P(NamedDecl, hasUnderlyingDecl, internal::Matcher<NamedDecl>,
 ///   class X : public Y {};
 ///   void z(Y y, X x) { y.m(); (g()).m(); x.m(); }
 /// \endcode
-/// cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("Y")))))
-///   matches `y.m()` and `(g()).m()`.
-/// cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("X")))))
-///   matches `x.m()`.
-/// cxxMemberCallExpr(on(callExpr()))
-///   matches `(g()).m()`.
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("Y")))))}
+///   matches \match{y.m()} and \match{(g()).m()}.
+/// The matcher
+/// \matcher{cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("X")))))}
+///   matches \match{x.m()}.
+/// The matcher \matcher{cxxMemberCallExpr(on(callExpr()))}
+///   matches \match{(g()).m()}.
 ///
 /// FIXME: Overload to allow directly matching types?
 AST_MATCHER_P(CXXMemberCallExpr, on, internal::Matcher<Expr>,
@@ -3702,17 +4964,17 @@ AST_MATCHER_P(CXXMemberCallExpr, on, internal::Matcher<Expr>,
           InnerMatcher.matches(*ExprNode, Finder, Builder));
 }
 
-
 /// Matches on the receiver of an ObjectiveC Message expression.
 ///
-/// Example
-/// matcher = objCMessageExpr(hasReceiverType(asString("UIWebView *")));
-/// matches the [webView ...] message invocation.
 /// \code
 ///   NSString *webViewJavaScript = ...
 ///   UIWebView *webView = ...
 ///   [webView stringByEvaluatingJavaScriptFromString:webViewJavascript];
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher \matcher{objCMessageExpr(hasReceiverType(asString("UIWebView
+/// *")))} matches
+/// \match{[webViewstringByEvaluatingJavaScriptFromString:webViewJavascript];}
 AST_MATCHER_P(ObjCMessageExpr, hasReceiverType, internal::Matcher<QualType>,
               InnerMatcher) {
   const QualType TypeDecl = Node.getReceiverType();
@@ -3721,66 +4983,63 @@ AST_MATCHER_P(ObjCMessageExpr, hasReceiverType, internal::Matcher<QualType>,
 
 /// Returns true when the Objective-C method declaration is a class method.
 ///
-/// Example
-/// matcher = objcMethodDecl(isClassMethod())
-/// matches
+/// Given
 /// \code
 /// @interface I + (void)foo; @end
-/// \endcode
-/// but not
-/// \code
 /// @interface I - (void)bar; @end
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher \matcher{objcMethodDecl(isClassMethod())}
+/// matches \match{@interface I + (void)foo; @end}
+/// but does not match \nomatch{interface I + (void)foo; @end}
 AST_MATCHER(ObjCMethodDecl, isClassMethod) {
   return Node.isClassMethod();
 }
 
 /// Returns true when the Objective-C method declaration is an instance method.
 ///
-/// Example
-/// matcher = objcMethodDecl(isInstanceMethod())
-/// matches
+/// Given
 /// \code
 /// @interface I - (void)bar; @end
-/// \endcode
-/// but not
-/// \code
 /// @interface I + (void)foo; @end
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher \matcher{objcMethodDecl(isInstanceMethod())}
+/// matches \match{@interface I - (void)bar; @end}
+/// but does not match \nomatch{@interface I - (void)foo; @end}
+/// \compile_args{-ObjC}
 AST_MATCHER(ObjCMethodDecl, isInstanceMethod) {
   return Node.isInstanceMethod();
 }
 
 /// Returns true when the Objective-C message is sent to a class.
 ///
-/// Example
-/// matcher = objcMessageExpr(isClassMessage())
-/// matches
+/// Given
 /// \code
 ///   [NSString stringWithFormat:@"format"];
-/// \endcode
-/// but not
-/// \code
 ///   NSString *x = @"hello";
 ///   [x containsString:@"h"];
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher \matcher{objcMessageExpr(isClassMessage())}
+/// matches \match{[NSString stringWithFormat:@"format"];}
+/// but does not match \nomatch{[[x containsString:@"h"]}
 AST_MATCHER(ObjCMessageExpr, isClassMessage) {
   return Node.isClassMessage();
 }
 
 /// Returns true when the Objective-C message is sent to an instance.
 ///
-/// Example
-/// matcher = objcMessageExpr(isInstanceMessage())
-/// matches
+/// Given
 /// \code
 ///   NSString *x = @"hello";
 ///   [x containsString:@"h"];
-/// \endcode
-/// but not
-/// \code
 ///   [NSString stringWithFormat:@"format"];
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher \matcher{objcMessageExpr(isInstanceMessage())}
+/// matches \match{[x containsString:@"h"];}
+/// but does not match \nomatch{[NSString stringWithFormat:@"format"];}
 AST_MATCHER(ObjCMessageExpr, isInstanceMessage) {
   return Node.isInstanceMessage();
 }
@@ -3788,13 +5047,15 @@ AST_MATCHER(ObjCMessageExpr, isInstanceMessage) {
 /// Matches if the Objective-C message is sent to an instance,
 /// and the inner matcher matches on that instance.
 ///
-/// For example the method call in
+/// Given
 /// \code
 ///   NSString *x = @"hello";
 ///   [x containsString:@"h"];
 /// \endcode
-/// is matched by
-/// objcMessageExpr(hasReceiver(declRefExpr(to(varDecl(hasName("x"))))))
+/// \compile_args{-ObjC}
+/// The matcher
+/// \matcher{objcMessageExpr(hasReceiver(declRefExpr(to(varDecl(hasName("x"))))))}
+/// matches \match{[x containsString:@"h"];}
 AST_MATCHER_P(ObjCMessageExpr, hasReceiver, internal::Matcher<Expr>,
               InnerMatcher) {
   const Expr *ReceiverNode = Node.getInstanceReceiver();
@@ -3805,12 +5066,14 @@ AST_MATCHER_P(ObjCMessageExpr, hasReceiver, internal::Matcher<Expr>,
 
 /// Matches when BaseName == Selector.getAsString()
 ///
-///  matcher = objCMessageExpr(hasSelector("loadHTMLString:baseURL:"));
-///  matches the outer message expr in the code below, but NOT the message
-///  invocation for self.bodyView.
 /// \code
 ///     [self.bodyView loadHTMLString:html baseURL:NULL];
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher
+/// \matcher{objCMessageExpr(hasSelector("loadHTMLString:baseURL:"));} matches
+/// the outer message expr in the code below, but NOT the message invocation
+/// for self.bodyView.
 AST_MATCHER_P(ObjCMessageExpr, hasSelector, std::string, BaseName) {
   Selector Sel = Node.getSelector();
   return BaseName == Sel.getAsString();
@@ -3819,12 +5082,13 @@ AST_MATCHER_P(ObjCMessageExpr, hasSelector, std::string, BaseName) {
 /// Matches when at least one of the supplied string equals to the
 /// Selector.getAsString()
 ///
-///  matcher = objCMessageExpr(hasSelector("methodA:", "methodB:"));
-///  matches both of the expressions below:
 /// \code
 ///     [myObj methodA:argA];
 ///     [myObj methodB:argB];
 /// \endcode
+/// \compile_args{-ObjC}
+///  The matcher \matcher{objCMessageExpr(hasSelector("methodA:", "methodB:"));}
+///  matches \match{[myObj methodA:argA];} and \match{[myObj methodB:argB];}
 extern const internal::VariadicFunction<internal::Matcher<ObjCMessageExpr>,
                                         StringRef,
                                         internal::hasAnySelectorFunc>
@@ -3832,12 +5096,17 @@ extern const internal::VariadicFunction<internal::Matcher<ObjCMessageExpr>,
 
 /// Matches ObjC selectors whose name contains
 /// a substring matched by the given RegExp.
-///  matcher = objCMessageExpr(matchesSelector("loadHTMLString\:baseURL?"));
-///  matches the outer message expr in the code below, but NOT the message
-///  invocation for self.bodyView.
+///
+/// Given
 /// \code
 ///     [self.bodyView loadHTMLString:html baseURL:NULL];
 /// \endcode
+/// \compile_args{-ObjC}
+///
+/// The matcher
+/// \matcher{objCMessageExpr(matchesSelector("loadHTMLString\:baseURL?"))}
+/// matches the outer message expr in the code below, but NOT the message
+/// invocation for self.bodyView.
 AST_MATCHER_REGEX(ObjCMessageExpr, matchesSelector, RegExp) {
   std::string SelectorString = Node.getSelector().getAsString();
   return RegExp->match(SelectorString);
@@ -3853,21 +5122,22 @@ AST_MATCHER(ObjCMessageExpr, hasNullSelector) {
 
 /// Matches when the selector is a Unary Selector
 ///
-///  matcher = objCMessageExpr(matchesSelector(hasUnarySelector());
-///  matches self.bodyView in the code below, but NOT the outer message
-///  invocation of "loadHTMLString:baseURL:".
+/// Given
 /// \code
 ///     [self.bodyView loadHTMLString:html baseURL:NULL];
 /// \endcode
+/// \compile_args{-ObjC}
+///
+///  The matcher \matcher{objCMessageExpr(matchesSelector(hasUnarySelector());}
+///  matches \match{self.bodyView}, but does not match the outer message
+///  invocation of "loadHTMLString:baseURL:".
 AST_MATCHER(ObjCMessageExpr, hasUnarySelector) {
   return Node.getSelector().isUnarySelector();
 }
 
 /// Matches when the selector is a keyword selector
 ///
-/// objCMessageExpr(hasKeywordSelector()) matches the generated setFrame
-/// message expression in
-///
+/// Given
 /// \code
 ///   UIWebView *webView = ...;
 ///   CGRect bodyFrame = webView.frame;
@@ -3875,21 +5145,25 @@ AST_MATCHER(ObjCMessageExpr, hasUnarySelector) {
 ///   webView.frame = bodyFrame;
 ///   //     ^---- matches here
 /// \endcode
+/// \compile_args{-ObjC}
+///
+/// The matcher \matcher{objCMessageExpr(hasKeywordSelector())} matches the
+/// generated setFrame message expression in
 AST_MATCHER(ObjCMessageExpr, hasKeywordSelector) {
   return Node.getSelector().isKeywordSelector();
 }
 
 /// Matches when the selector has the specified number of arguments
 ///
-///  matcher = objCMessageExpr(numSelectorArgs(0));
-///  matches self.bodyView in the code below
-///
-///  matcher = objCMessageExpr(numSelectorArgs(2));
-///  matches the invocation of "loadHTMLString:baseURL:" but not that
-///  of self.bodyView
 /// \code
 ///     [self.bodyView loadHTMLString:html baseURL:NULL];
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher \matcher{objCMessageExpr(numSelectorArgs(0))}
+/// matches \match{self.bodyView}.
+/// The matcher \matcher{objCMessageExpr(numSelectorArgs(2))}
+/// matches the invocation of \match{loadHTMLString:baseURL:}
+/// but does not match \nomatch{self.bodyView}
 AST_MATCHER_P(ObjCMessageExpr, numSelectorArgs, unsigned, N) {
   return Node.getSelector().getNumArgs() == N;
 }
@@ -3901,13 +5175,21 @@ AST_MATCHER_P(ObjCMessageExpr, numSelectorArgs, unsigned, N) {
 ///   class Y { void x() { this->x(); x(); Y y; y.x(); } };
 ///   void f() { f(); }
 /// \endcode
-/// callExpr(callee(expr()))
-///   matches this->x(), x(), y.x(), f()
-/// with callee(...)
-///   matching this->x, x, y.x, f respectively
+/// \compile_args{-std=c++}
+/// The matcher \matcher{callExpr(callee(expr().bind("callee")))}
+/// matches \match{this->x()}, \match{x()}, \match{y.x()}, \match{f()}
+/// with \matcher{type=sub$expr()} inside of \c callee
+/// matching \match{sub=callee$this->x}, \match{sub=callee$x},
+/// \match{sub=callee$y.x}, \match{sub=callee$f} respectively
 ///
 /// Given
 /// \code
+///   struct Dummy {};
+///   // makes sure there is a callee, otherwise there would be no callee,
+///   // just a builtin operator
+///   Dummy operator+(Dummy, Dummy);
+///   // not defining a '*' operator
+///
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
 ///       return (0 + ... + args);
@@ -3918,10 +5200,14 @@ AST_MATCHER_P(ObjCMessageExpr, numSelectorArgs, unsigned, N) {
 ///       return (args * ... * 1);
 ///   }
 /// \endcode
-/// cxxFoldExpr(callee(expr()))
-///   matches (args * ... * 1)
-/// with callee(...)
-///   matching *
+/// \compile_args{-std=c++17-or-later}
+/// The matcher \matcher{cxxFoldExpr(callee(expr().bind("op")))}
+/// matches \match{(0 + ... + args)}
+/// with \matcher{type=sub$callee(...)} matching \match{sub=op$*},
+/// but does not match \nomatch{(args * ... * 1)}.
+/// A \c CXXFoldExpr only has an \c UnresolvedLookupExpr as a callee.
+/// When there are no define operators that could be used instead of builtin
+/// ones, then there will be no \c callee .
 ///
 /// Note: Callee cannot take the more general internal::Matcher<Expr>
 /// because this introduces ambiguous overloads with calls to Callee taking a
@@ -3940,16 +5226,16 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(callee,
 /// given matcher; or 2) if the Obj-C message expression's callee's method
 /// declaration matches the given matcher.
 ///
-/// Example matches y.x() (matcher = callExpr(callee(
-///                                    cxxMethodDecl(hasName("x")))))
+/// Example 1
 /// \code
 ///   class Y { public: void x(); };
 ///   void z() { Y y; y.x(); }
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{callExpr(callee(cxxMethodDecl(hasName("x"))))}
+/// matches \match{y.x()}
 ///
-/// Example 2. Matches [I foo] with
-/// objcMessageExpr(callee(objcMethodDecl(hasName("foo"))))
-///
+/// Example 2
 /// \code
 ///   @interface I: NSObject
 ///   +(void)foo;
@@ -3957,6 +5243,10 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(callee,
 ///   ...
 ///   [I foo]
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher
+/// \matcher{objcMessageExpr(callee(objcMethodDecl(hasName("foo"))))}
+/// matches \match{[I foo]}
 AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
     callee, AST_POLYMORPHIC_SUPPORTED_TYPES(ObjCMessageExpr, CallExpr),
     internal::Matcher<Decl>, InnerMatcher, 1) {
@@ -3976,12 +5266,7 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
 /// Matches if the expression's or declaration's type matches a type
 /// matcher.
 ///
-/// Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-///             and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-///             and U (matcher = typedefDecl(hasType(asString("int")))
-///             and friend class X (matcher = friendDecl(hasType("X"))
-///             and public virtual X (matcher = cxxBaseSpecifier(hasType(
-///                                               asString("class X")))
+/// Exmaple
 /// \code
 ///  class X {};
 ///  void y(X &x) { x; X z; }
@@ -3989,6 +5274,19 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
 ///  class Y { friend class X; };
 ///  class Z : public virtual X {};
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{expr(hasType(cxxRecordDecl(hasName("X"))))}
+/// matches \match{x} and \match{z}.
+/// The matcher \matcher{varDecl(hasType(cxxRecordDecl(hasName("X"))))}
+/// matches \match{type=name$z}
+/// The matcher \matcher{typedefDecl(hasType(asString("int")))}
+/// matches \match{typedef int U}
+/// The matcher \matcher{friendDecl(hasType(asString("class X")))}
+/// matches \match{friend class X}
+/// The matcher \matcher{cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+/// asString("X"))).bind("b")))} matches \match{class Z : public virtual X {}},
+/// with \matcher{type=sub$cxxBaseSpecifier(...)}
+/// matching \match{sub=b$public virtual X}.
 AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
     hasType,
     AST_POLYMORPHIC_SUPPORTED_TYPES(Expr, FriendDecl, TypedefNameDecl,
@@ -4009,24 +5307,34 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
 /// X, while varDecl(hasType(cxxRecordDecl(hasName("X")))) matches the
 /// declaration of x.
 ///
-/// Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X")))))
-///             and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X")))))
-///             and friend class X (matcher = friendDecl(hasType("X"))
-///             and public virtual X (matcher = cxxBaseSpecifier(hasType(
-///                                               cxxRecordDecl(hasName("X"))))
 /// \code
 ///  class X {};
 ///  void y(X &x) { x; X z; }
 ///  class Y { friend class X; };
 ///  class Z : public virtual X {};
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{expr(hasType(cxxRecordDecl(hasName("X"))))}
+/// matches \match{x} and \match{z}.
+/// The matcher \matcher{varDecl(hasType(cxxRecordDecl(hasName("X"))))}
+/// matches \match{type=name$z}.
+/// The matcher \matcher{friendDecl(hasType(asString("class X")))}
+/// matches \match{friend class X}.
+/// The matcher \matcher{cxxRecordDecl(hasAnyBase(cxxBaseSpecifier(hasType(
+/// asString("X"))).bind("b")))} matches
+/// \match{class Z : public virtual X {}},
+/// with \matcher{type=sub$cxxBaseSpecifier(...)}
+/// matching \match{sub=b$public virtual X}.
 ///
-/// Example matches class Derived
-/// (matcher = cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base"))))))
+/// Given
 /// \code
 /// class Base {};
 /// class Derived : Base {};
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(hasAnyBase(hasType(cxxRecordDecl(hasName("Base")))))}
+/// matches \match{class Derived : Base {}}.
 ///
 /// Usable as: Matcher<Expr>, Matcher<FriendDecl>, Matcher<ValueDecl>,
 /// Matcher<CXXBaseSpecifier>
@@ -4043,25 +5351,32 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
 
 /// Matches if the type location of a node matches the inner matcher.
 ///
-/// Examples:
+/// Given
 /// \code
 ///   int x;
 /// \endcode
-/// declaratorDecl(hasTypeLoc(loc(asString("int"))))
-///   matches int x
+/// The matcher \matcher{declaratorDecl(hasTypeLoc(loc(asString("int"))))}
+/// matches \match{int x}.
 ///
+/// Given
 /// \code
-/// auto x = int(3);
+/// struct point { point(double, double); };
+/// point p = point(1.0, -1.0);
 /// \endcode
-/// cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("int"))))
-///   matches int(3)
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxTemporaryObjectExpr(hasTypeLoc(loc(asString("point"))))}
+/// matches \match{point(1.0, -1.0)}.
 ///
+/// Given
 /// \code
 /// struct Foo { Foo(int, int); };
-/// auto x = Foo(1, 2);
+/// Foo x = Foo(1, 2);
 /// \endcode
-/// cxxFunctionalCastExpr(hasTypeLoc(loc(asString("struct Foo"))))
-///   matches Foo(1, 2)
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxTemporaryObjectExpr(hasTypeLoc(
+///                           loc(asString("Foo"))))}
+/// matches \match{Foo(1, 2)}.
 ///
 /// Usable as: Matcher<BlockDecl>, Matcher<CXXBaseSpecifier>,
 ///   Matcher<CXXCtorInitializer>, Matcher<CXXFunctionalCastExpr>,
@@ -4094,22 +5409,25 @@ AST_POLYMORPHIC_MATCHER_P(
 ///   class Y { public: void x(); };
 ///   void z() { Y* y; y->x(); }
 /// \endcode
-/// cxxMemberCallExpr(on(hasType(asString("class Y *"))))
-///   matches y->x()
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMemberCallExpr(on(hasType(asString("Y *"))))}
+/// matches \match{y->x()}
 AST_MATCHER_P(QualType, asString, std::string, Name) {
   return Name == Node.getAsString();
 }
 
 /// Matches if the matched type is a pointer type and the pointee type
-/// matches the specified matcher.
+///   matches the specified matcher.
 ///
-/// Example matches y->x()
-///   (matcher = cxxMemberCallExpr(on(hasType(pointsTo
-///      cxxRecordDecl(hasName("Y")))))))
+/// Given
 /// \code
 ///   class Y { public: void x(); };
 ///   void z() { Y *y; y->x(); }
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMemberCallExpr(on(hasType(pointsTo(
+///      qualType()))))}
+/// matches \match{y->x()}
 AST_MATCHER_P(
     QualType, pointsTo, internal::Matcher<QualType>,
     InnerMatcher) {
@@ -4117,7 +5435,19 @@ AST_MATCHER_P(
           InnerMatcher.matches(Node->getPointeeType(), Finder, Builder));
 }
 
+/// Matches if the matched type is a pointer type and the pointee type
+///   matches the specified matcher.
 /// Overloaded to match the pointee type's declaration.
+///
+/// Given
+/// \code
+///   class Y { public: void x(); };
+///   void z() { Y *y; y->x(); }
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMemberCallExpr(on(hasType(pointsTo(
+///      cxxRecordDecl(hasName("Y"))))))}
+/// matches \match{y->x()}
 AST_MATCHER_P_OVERLOAD(QualType, pointsTo, internal::Matcher<Decl>,
                        InnerMatcher, 1) {
   return pointsTo(qualType(hasDeclaration(InnerMatcher)))
@@ -4131,9 +5461,12 @@ AST_MATCHER_P_OVERLOAD(QualType, pointsTo, internal::Matcher<Decl>,
 /// \code
 ///   class A {};
 ///   using B = A;
+///   B b;
 /// \endcode
-/// The matcher type(hasUnqualifiedDesugaredType(recordType())) matches
-/// both B and A.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher
+/// \matcher{varDecl(hasType(hasUnqualifiedDesugaredType(recordType())))}
+/// matches \match{B b}.
 AST_MATCHER_P(Type, hasUnqualifiedDesugaredType, internal::Matcher<Type>,
               InnerMatcher) {
   return InnerMatcher.matches(*Node.getUnqualifiedDesugaredType(), Finder,
@@ -4143,8 +5476,7 @@ AST_MATCHER_P(Type, hasUnqualifiedDesugaredType, internal::Matcher<Type>,
 /// 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(cxxRecordDecl(hasName("X"))))))
+/// Given
 /// \code
 ///   class X {
 ///     void a(X b) {
@@ -4153,24 +5485,29 @@ AST_MATCHER_P(Type, hasUnqualifiedDesugaredType, internal::Matcher<Type>,
 ///     }
 ///   };
 /// \endcode
-AST_MATCHER_P(QualType, references, internal::Matcher<QualType>,
-              InnerMatcher) {
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{varDecl(hasType(references(qualType())))} matches
+/// \match{X &x = b} and \match{const X &y = b}.
+AST_MATCHER_P(QualType, references, internal::Matcher<QualType>, InnerMatcher) {
   return (!Node.isNull() && Node->isReferenceType() &&
           InnerMatcher.matches(Node->getPointeeType(), Finder, Builder));
 }
 
 /// Matches QualTypes whose canonical type matches InnerMatcher.
 ///
-/// Given:
+/// Given
 /// \code
 ///   typedef int &int_ref;
 ///   int a;
 ///   int_ref b = a;
 /// \endcode
-///
-/// \c varDecl(hasType(qualType(referenceType()))))) will not match the
-/// declaration of b but \c
-/// varDecl(hasType(qualType(hasCanonicalType(referenceType())))))) does.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{varDecl(hasType(qualType(referenceType())))}
+/// does not match \nomatch{int_ref b = a},
+/// but the matcher
+/// \matcher{varDecl(hasType(qualType(hasCanonicalType(referenceType()))))}
+/// does match \match{int_ref b = a}.
 AST_MATCHER_P(QualType, hasCanonicalType, internal::Matcher<QualType>,
               InnerMatcher) {
   if (Node.isNull())
@@ -4178,7 +5515,23 @@ AST_MATCHER_P(QualType, hasCanonicalType, internal::Matcher<QualType>,
   return InnerMatcher.matches(Node.getCanonicalType(), Finder, Builder);
 }
 
+/// Matches if the matched type is a reference type and the referenced
+/// type matches the specified matcher.
 /// Overloaded to match the referenced type's declaration.
+///
+/// Given
+/// \code
+///   class X {
+///     void a(X b) {
+///       X &x = b;
+///       const X &y = b;
+///     }
+///   };
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{varDecl(hasType(references(cxxRecordDecl(hasName("X")))))} matches
+/// \match{X &x = b} and \match{const X &y = b}.
 AST_MATCHER_P_OVERLOAD(QualType, references, internal::Matcher<Decl>,
                        InnerMatcher, 1) {
   return references(qualType(hasDeclaration(InnerMatcher)))
@@ -4192,14 +5545,17 @@ AST_MATCHER_P_OVERLOAD(QualType, references, internal::Matcher<Decl>,
 /// \code
 ///   class Y { public: void m(); };
 ///   Y g();
-///   class X : public Y { void g(); };
+///   class X : public Y { public: void g(); };
 ///   void z(Y y, X x) { y.m(); x.m(); x.g(); (g()).m(); }
 /// \endcode
-/// cxxMemberCallExpr(onImplicitObjectArgument(hasType(
-///     cxxRecordDecl(hasName("Y")))))
-///   matches `y.m()`, `x.m()` and (g()).m(), but not `x.g()`.
-/// cxxMemberCallExpr(on(callExpr()))
-///   does not match `(g()).m()`, because the parens are not ignored.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMemberCallExpr(onImplicitObjectArgument(hasType(
+///     cxxRecordDecl(hasName("Y")))))}
+/// matches \match{y.m()}, \match{x.m()} and \match{(g()).m()}
+/// but does not match \nomatch{x.g()}.
+/// The matcher \matcher{cxxMemberCallExpr(on(callExpr()))}
+/// matches \match{(g()).m()}, because the parens are ignored.
+/// FIXME: should they be ignored? (ignored bc of `on`)
 ///
 /// FIXME: Overload to allow directly matching types?
 AST_MATCHER_P(CXXMemberCallExpr, onImplicitObjectArgument,
@@ -4210,21 +5566,20 @@ AST_MATCHER_P(CXXMemberCallExpr, onImplicitObjectArgument,
 }
 
 /// Matches if the type of the expression's implicit object argument either
-/// matches the InnerMatcher, or is a pointer to a type that matches the
+///   matches the InnerMatcher, or is a pointer to a type that matches the
 /// InnerMatcher.
 ///
 /// Given
 /// \code
-///   class Y { public: void m(); };
-///   class X : public Y { void g(); };
-///   void z() { Y y; y.m(); Y *p; p->m(); X x; x.m(); x.g(); }
+///   class Y { public: void m() const; };
+///   class X : public Y { public: void g(); };
+///   void z() { const Y y; y.m(); const Y *p; p->m(); X x; x.m(); x.g(); }
 /// \endcode
-/// cxxMemberCallExpr(thisPointerType(hasDeclaration(
-///     cxxRecordDecl(hasName("Y")))))
-///   matches `y.m()`, `p->m()` and `x.m()`.
-/// cxxMemberCallExpr(thisPointerType(hasDeclaration(
-///     cxxRecordDecl(hasName("X")))))
-///   matches `x.g()`.
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxMemberCallExpr(thisPointerType(isConstQualified()))}
+/// matches \match{y.m()}, \match{x.m()} and \match{p->m()},
+/// but not \nomatch{x.g()}.
 AST_MATCHER_P_OVERLOAD(CXXMemberCallExpr, thisPointerType,
                        internal::Matcher<QualType>, InnerMatcher, 0) {
   return onImplicitObjectArgument(
@@ -4233,6 +5588,20 @@ AST_MATCHER_P_OVERLOAD(CXXMemberCallExpr, thisPointerType,
 }
 
 /// Overloaded to match the type's declaration.
+///
+/// Given
+/// \code
+///   class Y { public: void m(); };
+///   class X : public Y { public: void g(); };
+///   void z() { Y y; y.m(); Y *p; p->m(); X x; x.m(); x.g(); }
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMemberCallExpr(thisPointerType(
+///     cxxRecordDecl(hasName("Y"))))}
+///   matches \match{y.m()}, \match{p->m()} and \match{x.m()}.
+/// The matcher \matcher{cxxMemberCallExpr(thisPointerType(
+///     cxxRecordDecl(hasName("X"))))}
+///   matches \match{x.g()}.
 AST_MATCHER_P_OVERLOAD(CXXMemberCallExpr, thisPointerType,
                        internal::Matcher<Decl>, InnerMatcher, 1) {
   return onImplicitObjectArgument(
@@ -4243,14 +5612,17 @@ AST_MATCHER_P_OVERLOAD(CXXMemberCallExpr, thisPointerType,
 /// Matches a DeclRefExpr that refers to a declaration that matches the
 /// specified matcher.
 ///
-/// Example matches x in if(x)
-///     (matcher = declRefExpr(to(varDecl(hasName("x")))))
+/// Given
 /// \code
-///   bool x;
-///   if (x) {}
+///   void foo() {
+///     bool x;
+///     if (x) {}
+///   }
 /// \endcode
-AST_MATCHER_P(DeclRefExpr, to, internal::Matcher<Decl>,
-              InnerMatcher) {
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{declRefExpr(to(varDecl(hasName("x"))))}
+/// matches \match{x} inside the condition of the if-stmt.
+AST_MATCHER_P(DeclRefExpr, to, internal::Matcher<Decl>, InnerMatcher) {
   const Decl *DeclNode = Node.getDecl();
   return (DeclNode != nullptr &&
           InnerMatcher.matches(*DeclNode, Finder, Builder));
@@ -4259,22 +5631,24 @@ AST_MATCHER_P(DeclRefExpr, to, internal::Matcher<Decl>,
 /// Matches if a node refers to a declaration through a specific
 /// using shadow declaration.
 ///
-/// Examples:
+/// Given
 /// \code
 ///   namespace a { int f(); }
 ///   using a::f;
 ///   int x = f();
 /// \endcode
-/// declRefExpr(throughUsingDecl(anything()))
-///   matches \c f
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{declRefExpr(throughUsingDecl(anything()))}
+/// matches \match{f}
 ///
 /// \code
 ///   namespace a { class X{}; }
 ///   using a::X;
 ///   X x;
 /// \endcode
-/// typeLoc(loc(usingType(throughUsingDecl(anything()))))
-///   matches \c X
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{typeLoc(loc(usingType(throughUsingDecl(anything()))))}
+/// matches \match{X}
 ///
 /// Usable as: Matcher<DeclRefExpr>, Matcher<UsingType>
 AST_POLYMORPHIC_MATCHER_P(throughUsingDecl,
@@ -4299,9 +5673,11 @@ AST_POLYMORPHIC_MATCHER_P(throughUsingDecl,
 ///     bar(t);
 ///   }
 /// \endcode
-/// unresolvedLookupExpr(hasAnyDeclaration(
-///     functionTemplateDecl(hasName("foo"))))
-///   matches \c foo in \c foo(t); but not \c bar in \c bar(t);
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{unresolvedLookupExpr(hasAnyDeclaration(
+///     functionTemplateDecl(hasName("foo"))))}
+/// matches \match{foo} in \c foo(t);
+/// but does not match \nomatch{bar} in \c bar(t);
 AST_MATCHER_P(OverloadExpr, hasAnyDeclaration, internal::Matcher<Decl>,
               InnerMatcher) {
   return matchesFirstInPointerRange(InnerMatcher, Node.decls_begin(),
@@ -4313,11 +5689,14 @@ AST_MATCHER_P(OverloadExpr, hasAnyDeclaration, internal::Matcher<Decl>,
 ///
 /// Given
 /// \code
-///   int a, b;
-///   int c;
+///   void foo() {
+///     int a, b;
+///     int c;
+///   }
 /// \endcode
-/// declStmt(hasSingleDecl(anything()))
-///   matches 'int c;' but not 'int a, b;'.
+/// The matcher \matcher{declStmt(hasSingleDecl(anything()))}
+/// matches \match{int c;}
+/// but does not match \nomatch{int a, b;}
 AST_MATCHER_P(DeclStmt, hasSingleDecl, internal::Matcher<Decl>, InnerMatcher) {
   if (Node.isSingleDecl()) {
     const Decl *FoundDecl = Node.getSingleDecl();
@@ -4329,11 +5708,15 @@ AST_MATCHER_P(DeclStmt, hasSingleDecl, internal::Matcher<Decl>, InnerMatcher) {
 /// Matches a variable declaration that has an initializer expression
 /// that matches the given matcher.
 ///
-/// Example matches x (matcher = varDecl(hasInitializer(callExpr())))
+/// Given
 /// \code
-///   bool y() { return true; }
-///   bool x = y();
+///   int y() { return 0; }
+///   void foo() {
+///     int x = y();
+///   }
 /// \endcode
+/// The matcher \matcher{varDecl(hasInitializer(callExpr()))}
+/// matches \match{type=name$x}
 AST_MATCHER_P(
     VarDecl, hasInitializer, internal::Matcher<Expr>,
     InnerMatcher) {
@@ -4345,10 +5728,13 @@ AST_MATCHER_P(
 /// Matches a variable serving as the implicit variable for a lambda init-
 /// capture.
 ///
-/// Example matches x (matcher = varDecl(isInitCapture()))
+/// Given
 /// \code
-/// auto f = [x=3]() { return x; };
+/// auto f = [x = 3]() { return x; };
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{varDecl(isInitCapture())}
+/// matches \match{x = 3}.
 AST_MATCHER(VarDecl, isInitCapture) { return Node.isInitCapture(); }
 
 /// Matches each lambda capture in a lambda expression.
@@ -4356,14 +5742,19 @@ AST_MATCHER(VarDecl, isInitCapture) { return Node.isInitCapture(); }
 /// Given
 /// \code
 ///   int main() {
-///     int x, y;
+///     int x;
+///     int y;
 ///     float z;
 ///     auto f = [=]() { return x + y + z; };
 ///   }
 /// \endcode
-/// lambdaExpr(forEachLambdaCapture(
-///     lambdaCapture(capturesVar(varDecl(hasType(isInteger()))))))
-/// will trigger two matches, binding for 'x' and 'y' respectively.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{lambdaExpr(forEachLambdaCapture(
+///     lambdaCapture(capturesVar(
+///     varDecl(hasType(isInteger())).bind("captured")))))}
+/// matches \match{count=2$[=]() { return x + y + z; }} two times,
+/// with \matcher{type=sub$varDecl(hasType(isInteger()))} matching
+/// \match{sub=captured$int x} and \match{sub=captured$int y}.
 AST_MATCHER_P(LambdaExpr, forEachLambdaCapture,
               internal::Matcher<LambdaCapture>, InnerMatcher) {
   BoundNodesTreeBuilder Result;
@@ -4383,7 +5774,7 @@ AST_MATCHER_P(LambdaExpr, forEachLambdaCapture,
 
 /// \brief Matches a static variable with local scope.
 ///
-/// Example matches y (matcher = varDecl(isStaticLocal()))
+/// Given
 /// \code
 /// void f() {
 ///   int x;
@@ -4391,6 +5782,8 @@ AST_MATCHER_P(LambdaExpr, forEachLambdaCapture,
 /// }
 /// static int z;
 /// \endcode
+/// The matcher \matcher{varDecl(isStaticLocal())}
+/// matches \match{type=name$y}
 AST_MATCHER(VarDecl, isStaticLocal) {
   return Node.isStaticLocal();
 }
@@ -4398,7 +5791,7 @@ AST_MATCHER(VarDecl, isStaticLocal) {
 /// Matches a variable declaration that has function scope and is a
 /// non-static local variable.
 ///
-/// Example matches x (matcher = varDecl(hasLocalStorage())
+/// Given
 /// \code
 /// void f() {
 ///   int x;
@@ -4406,13 +5799,15 @@ AST_MATCHER(VarDecl, isStaticLocal) {
 /// }
 /// int z;
 /// \endcode
+/// The matcher \matcher{varDecl(hasLocalStorage())}
+/// matches \match{type=name$x}
 AST_MATCHER(VarDecl, hasLocalStorage) {
   return Node.hasLocalStorage();
 }
 
 /// Matches a variable declaration that does not have local storage.
 ///
-/// Example matches y and z (matcher = varDecl(hasGlobalStorage())
+/// Given
 /// \code
 /// void f() {
 ///   int x;
@@ -4420,14 +5815,15 @@ AST_MATCHER(VarDecl, hasLocalStorage) {
 /// }
 /// int z;
 /// \endcode
+/// The matcher \matcher{varDecl(hasGlobalStorage())}
+/// matches \match{type=name$y} and \match{type=name$z}
 AST_MATCHER(VarDecl, hasGlobalStorage) {
   return Node.hasGlobalStorage();
 }
 
 /// Matches a variable declaration that has automatic storage duration.
 ///
-/// Example matches x, but not y, z, or a.
-/// (matcher = varDecl(hasAutomaticStorageDuration())
+/// Given
 /// \code
 /// void f() {
 ///   int x;
@@ -4436,6 +5832,11 @@ AST_MATCHER(VarDecl, hasGlobalStorage) {
 /// }
 /// int a;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{varDecl(hasAutomaticStorageDuration())}
+/// matches \match{type=name$x}
+/// but does not match \nomatch{type=name$y}, \nomatch{type=name$z} or
+/// \nomatch{type=name$a}
 AST_MATCHER(VarDecl, hasAutomaticStorageDuration) {
   return Node.getStorageDuration() == SD_Automatic;
 }
@@ -4453,17 +5854,18 @@ AST_MATCHER(VarDecl, hasAutomaticStorageDuration) {
 /// int a;
 /// static int b;
 /// extern int c;
-/// varDecl(hasStaticStorageDuration())
-///   matches the function declaration y, a, b and c.
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{varDecl(hasStaticStorageDuration())}
+/// matches \match{type=name$y}, \match{type=name$a}, \match{type=name$b} and
+/// \match{type=name$c}
 AST_MATCHER(VarDecl, hasStaticStorageDuration) {
   return Node.getStorageDuration() == SD_Static;
 }
 
 /// Matches a variable declaration that has thread storage duration.
 ///
-/// Example matches z, but not x, z, or a.
-/// (matcher = varDecl(hasThreadStorageDuration())
+/// Given
 /// \code
 /// void f() {
 ///   int x;
@@ -4472,6 +5874,11 @@ AST_MATCHER(VarDecl, hasStaticStorageDuration) {
 /// }
 /// int a;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{varDecl(hasThreadStorageDuration())}
+/// matches \match{type=name$z}
+/// but does not match \nomatch{type=name$x}, \nomatch{type=name$z} or
+/// \nomatch{type=name$a}
 AST_MATCHER(VarDecl, hasThreadStorageDuration) {
   return Node.getStorageDuration() == SD_Thread;
 }
@@ -4479,7 +5886,7 @@ AST_MATCHER(VarDecl, hasThreadStorageDuration) {
 /// Matches a variable declaration that is an exception variable from
 /// a C++ catch block, or an Objective-C \@catch statement.
 ///
-/// Example matches x (matcher = varDecl(isExceptionVariable())
+/// Given
 /// \code
 /// void f(int y) {
 ///   try {
@@ -4487,6 +5894,9 @@ AST_MATCHER(VarDecl, hasThreadStorageDuration) {
 ///   }
 /// }
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{varDecl(isExceptionVariable())}
+/// matches \match{type=name$x}
 AST_MATCHER(VarDecl, isExceptionVariable) {
   return Node.isExceptionVariable();
 }
@@ -4494,11 +5904,15 @@ AST_MATCHER(VarDecl, isExceptionVariable) {
 /// Checks that a call expression or a constructor call expression has
 /// a specific number of arguments (including absent default arguments).
 ///
-/// Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2)))
+/// Given
 /// \code
 ///   void f(int x, int y);
-///   f(0, 0);
+///   void foo() {
+///     f(0, 0);
+///   }
 /// \endcode
+/// The matcher \matcher{callExpr(argumentCountIs(2))}
+/// matches \match{f(0, 0)}
 AST_POLYMORPHIC_MATCHER_P(argumentCountIs,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(
                               CallExpr, CXXConstructExpr,
@@ -4518,14 +5932,17 @@ AST_POLYMORPHIC_MATCHER_P(argumentCountIs,
 /// Checks that a call expression or a constructor call expression has at least
 /// the specified number of arguments (including absent default arguments).
 ///
-/// Example matches f(0, 0) and g(0, 0, 0)
-/// (matcher = callExpr(argumentCountAtLeast(2)))
+/// Given
 /// \code
 ///   void f(int x, int y);
 ///   void g(int x, int y, int z);
-///   f(0, 0);
-///   g(0, 0, 0);
+///   void foo() {
+///     f(0, 0);
+///     g(0, 0, 0);
+///   }
 /// \endcode
+/// The matcher \matcher{callExpr(argumentCountAtLeast(2))}
+/// matches \match{f(0, 0)} and \match{g(0, 0, 0)}
 AST_POLYMORPHIC_MATCHER_P(argumentCountAtLeast,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(
                               CallExpr, CXXConstructExpr,
@@ -4545,11 +5962,13 @@ AST_POLYMORPHIC_MATCHER_P(argumentCountAtLeast,
 /// Matches the n'th argument of a call expression or a constructor
 /// call expression.
 ///
-/// Example matches y in x(y)
-///     (matcher = callExpr(hasArgument(0, declRefExpr())))
+/// Given
 /// \code
 ///   void x(int) { int y; x(y); }
 /// \endcode
+/// The matcher \matcher{callExpr(hasArgument(0, declRefExpr().bind("arg")))}
+/// matches \match{x(y)},
+/// with \matcher{type=sub$declRefExpr()} matching \match{sub="arg"$y}.
 AST_POLYMORPHIC_MATCHER_P2(hasArgument,
                            AST_POLYMORPHIC_SUPPORTED_TYPES(
                                CallExpr, CXXConstructExpr,
@@ -4565,10 +5984,7 @@ AST_POLYMORPHIC_MATCHER_P2(hasArgument,
 
 /// Matches the operand that does not contain the parameter pack.
 ///
-/// Example matches `(0 + ... + args)` and `(args * ... * 1)`
-///     (matcher = cxxFoldExpr(hasFoldInit(expr())))
-///   with hasFoldInit(...)
-///     matching `0` and `1` respectively
+/// Given
 /// \code
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
@@ -4580,6 +5996,12 @@ AST_POLYMORPHIC_MATCHER_P2(hasArgument,
 ///       return (args * ... * 1);
 ///   }
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+///
+/// The matcher \matcher{cxxFoldExpr(hasFoldInit(expr().bind("init")))}
+/// matches \match{(0 + ... + args)} and \match{(args * ... * 1)}
+/// with \matcher{type=sub$hasFoldInit(expr().bind("init"))} matching
+/// \match{sub=init$0} and \match{sub=init$1}.
 AST_MATCHER_P(CXXFoldExpr, hasFoldInit, internal::Matcher<Expr>, InnerMacher) {
   const auto *const Init = Node.getInit();
   return Init && InnerMacher.matches(*Init, Finder, Builder);
@@ -4587,10 +6009,7 @@ AST_MATCHER_P(CXXFoldExpr, hasFoldInit, internal::Matcher<Expr>, InnerMacher) {
 
 /// Matches the operand that contains the parameter pack.
 ///
-/// Example matches `(0 + ... + args)`
-///     (matcher = cxxFoldExpr(hasPattern(expr())))
-///   with hasPattern(...)
-///     matching `args`
+/// Given
 /// \code
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
@@ -4602,6 +6021,12 @@ AST_MATCHER_P(CXXFoldExpr, hasFoldInit, internal::Matcher<Expr>, InnerMacher) {
 ///       return (args * ... * 1);
 ///   }
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+///
+/// The matcher \matcher{cxxFoldExpr(hasPattern(expr().bind("pattern")))}
+/// matches \match{(0 + ... + args)} and \match{(args * ... * 1)},
+/// with \matcher{type=sub$hasPattern(expr().bind("pattern"))} matching
+/// \match{count=2;sub=pattern$args} two times.
 AST_MATCHER_P(CXXFoldExpr, hasPattern, internal::Matcher<Expr>, InnerMacher) {
   const Expr *const Pattern = Node.getPattern();
   return Pattern && InnerMacher.matches(*Pattern, Finder, Builder);
@@ -4609,8 +6034,7 @@ AST_MATCHER_P(CXXFoldExpr, hasPattern, internal::Matcher<Expr>, InnerMacher) {
 
 /// Matches right-folding fold expressions.
 ///
-/// Example matches `(args * ... * 1)`
-///     (matcher = cxxFoldExpr(isRightFold()))
+/// Given
 /// \code
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
@@ -4622,12 +6046,15 @@ AST_MATCHER_P(CXXFoldExpr, hasPattern, internal::Matcher<Expr>, InnerMacher) {
 ///       return (args * ... * 1);
 ///   }
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+///
+/// The matcher \matcher{cxxFoldExpr(isRightFold())}
+/// matches \match{(args * ... * 1)}.
 AST_MATCHER(CXXFoldExpr, isRightFold) { return Node.isRightFold(); }
 
 /// Matches left-folding fold expressions.
 ///
-/// Example matches `(0 + ... + args)`
-///     (matcher = cxxFoldExpr(isLeftFold()))
+/// Given
 /// \code
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
@@ -4639,13 +6066,16 @@ AST_MATCHER(CXXFoldExpr, isRightFold) { return Node.isRightFold(); }
 ///       return (args * ... * 1);
 ///   }
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+///
+/// The matcher \matcher{cxxFoldExpr(isLeftFold())}
+/// matches \match{(0 + ... + args)}.
 AST_MATCHER(CXXFoldExpr, isLeftFold) { return Node.isLeftFold(); }
 
 /// Matches unary fold expressions, i.e. fold expressions without an
 /// initializer.
 ///
-/// Example matches `(args * ...)`
-///     (matcher = cxxFoldExpr(isUnaryFold()))
+/// Given
 /// \code
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
@@ -4657,12 +6087,15 @@ AST_MATCHER(CXXFoldExpr, isLeftFold) { return Node.isLeftFold(); }
 ///       return (args * ...);
 ///   }
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+///
+/// The matcher \matcher{cxxFoldExpr(isUnaryFold())}
+/// matches \match{(args * ...)}, but not \nomatch{(0 + ... + args)}.
 AST_MATCHER(CXXFoldExpr, isUnaryFold) { return Node.getInit() == nullptr; }
 
 /// Matches binary fold expressions, i.e. fold expressions with an initializer.
 ///
-/// Example matches `(0 + ... + args)`
-///     (matcher = cxxFoldExpr(isBinaryFold()))
+/// Given
 /// \code
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
@@ -4674,32 +6107,42 @@ AST_MATCHER(CXXFoldExpr, isUnaryFold) { return Node.getInit() == nullptr; }
 ///       return (args * ...);
 ///   }
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+///
+/// The matcher \matcher{cxxFoldExpr(isBinaryFold())}
+/// matches \match{(0 + ... + args)}.
 AST_MATCHER(CXXFoldExpr, isBinaryFold) { return Node.getInit() != nullptr; }
 
 /// Matches the n'th item of an initializer list expression.
 ///
-/// Example matches y.
-///     (matcher = initListExpr(hasInit(0, expr())))
+/// Given
 /// \code
-///   int x{y}.
+///   int y = 42;
+///   int x{y};
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{initListExpr(hasInit(0, expr()))}
+/// matches \match{{y}}.
 AST_MATCHER_P2(InitListExpr, hasInit, unsigned, N, internal::Matcher<Expr>,
                InnerMatcher) {
   return N < Node.getNumInits() &&
-          InnerMatcher.matches(*Node.getInit(N), Finder, Builder);
+         InnerMatcher.matches(*Node.getInit(N), Finder, Builder);
 }
 
 /// Matches declaration statements that contain a specific number of
 /// declarations.
 ///
-/// Example: Given
+/// Given
 /// \code
-///   int a, b;
-///   int c;
-///   int d = 2, e;
+///   void foo() {
+///     int a, b;
+///     int c;
+///     int d = 2, e;
+///   }
 /// \endcode
-/// declCountIs(2)
-///   matches 'int a, b;' and 'int d = 2, e;', but not 'int c;'.
+/// The matcher \matcher{declStmt(declCountIs(2))}
+/// matches \match{int a, b;} and \match{int d = 2, e;},
+/// but does not match \nomatch{int c;}
 AST_MATCHER_P(DeclStmt, declCountIs, unsigned, N) {
   return std::distance(Node.decl_begin(), Node.decl_end()) == (ptrdiff_t)N;
 }
@@ -4709,20 +6152,21 @@ AST_MATCHER_P(DeclStmt, declCountIs, unsigned, N) {
 /// Note that this does not work for global declarations because the AST
 /// breaks up multiple-declaration DeclStmt's into multiple single-declaration
 /// DeclStmt's.
-/// Example: Given non-global declarations
-/// \code
-///   int a, b = 0;
-///   int c;
-///   int d = 2, e;
-/// \endcode
-/// declStmt(containsDeclaration(
-///       0, varDecl(hasInitializer(anything()))))
-///   matches only 'int d = 2, e;', and
-/// declStmt(containsDeclaration(1, varDecl()))
+///
+/// Given non-global declarations
 /// \code
-///   matches 'int a, b = 0' as well as 'int d = 2, e;'
-///   but 'int c;' is not matched.
+///   void foo() {
+///     int a, b = 0;
+///     int c;
+///     int d = 2, e;
+///   }
 /// \endcode
+/// The matcher \matcher{declStmt(containsDeclaration(
+///       0, varDecl(hasInitializer(anything()))))}
+/// matches \match{int d = 2, e;}.
+/// The matcher \matcher{declStmt(containsDeclaration(1, varDecl()))}
+/// matches \match{int a, b = 0;} and \match{int d = 2, e;}
+/// but does not match \nomatch{int c;}.
 AST_MATCHER_P2(DeclStmt, containsDeclaration, unsigned, N,
                internal::Matcher<Decl>, InnerMatcher) {
   const unsigned NumDecls = std::distance(Node.decl_begin(), Node.decl_end());
@@ -4737,15 +6181,16 @@ AST_MATCHER_P2(DeclStmt, containsDeclaration, unsigned, N,
 ///
 /// Given
 /// \code
-///   try {
-///     // ...
-///   } catch (int) {
-///     // ...
-///   } catch (...) {
-///     // ...
+///   void foo() {
+///     try {}
+///     catch (int) {}
+///     catch (...) {}
 ///   }
 /// \endcode
-/// cxxCatchStmt(isCatchAll()) matches catch(...) but not catch(int).
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxCatchStmt(isCatchAll())}
+/// matches \match{catch (...) {}}
+/// but does not match \nomatch{catch(int)}
 AST_MATCHER(CXXCatchStmt, isCatchAll) {
   return Node.getExceptionDecl() == nullptr;
 }
@@ -4759,10 +6204,11 @@ AST_MATCHER(CXXCatchStmt, isCatchAll) {
 ///     int foo_;
 ///   };
 /// \endcode
-/// cxxRecordDecl(has(cxxConstructorDecl(
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(has(cxxConstructorDecl(
 ///   hasAnyConstructorInitializer(anything())
-/// )))
-///   record matches Foo, hasAnyConstructorInitializer matches foo_(1)
+/// )))}
+/// matches \match{type=name$Foo}, hasAnyConstructorInitializer matches foo_(1)
 AST_MATCHER_P(CXXConstructorDecl, hasAnyConstructorInitializer,
               internal::Matcher<CXXCtorInitializer>, InnerMatcher) {
   auto MatchIt = matchesFirstInPointerRange(InnerMatcher, Node.init_begin(),
@@ -4781,9 +6227,11 @@ AST_MATCHER_P(CXXConstructorDecl, hasAnyConstructorInitializer,
 ///     int foo_;
 ///   };
 /// \endcode
-/// cxxRecordDecl(has(cxxConstructorDecl(hasAnyConstructorInitializer(
-///     forField(hasName("foo_"))))))
-///   matches Foo
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(has(cxxConstructorDecl(hasAnyConstructorInitializer(
+///     forField(hasName("foo_"))))))}
+/// matches \match{type=name$Foo}
 /// with forField matching foo_
 AST_MATCHER_P(CXXCtorInitializer, forField,
               internal::Matcher<FieldDecl>, InnerMatcher) {
@@ -4801,9 +6249,11 @@ AST_MATCHER_P(CXXCtorInitializer, forField,
 ///     int foo_;
 ///   };
 /// \endcode
-/// cxxRecordDecl(has(cxxConstructorDecl(hasAnyConstructorInitializer(
-///     withInitializer(integerLiteral(equals(1)))))))
-///   matches Foo
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(has(cxxConstructorDecl(hasAnyConstructorInitializer(
+///     withInitializer(integerLiteral(equals(1)))))))}
+/// matches \match{type=name$Foo}
 /// with withInitializer matching (1)
 AST_MATCHER_P(CXXCtorInitializer, withInitializer,
               internal::Matcher<Expr>, InnerMatcher) {
@@ -4817,14 +6267,17 @@ AST_MATCHER_P(CXXCtorInitializer, withInitializer,
 ///
 /// Given
 /// \code
+///   struct Bar { explicit Bar(const char*); };
 ///   struct Foo {
 ///     Foo() { }
 ///     Foo(int) : foo_("A") { }
-///     string foo_;
+///     Bar foo_{""};
 ///   };
 /// \endcode
-/// cxxConstructorDecl(hasAnyConstructorInitializer(isWritten()))
-///   will match Foo(int), but not Foo()
+/// \compile_args{-std=c++11-or-later}
+/// The matcher
+/// \matcher{cxxConstructorDecl(hasAnyConstructorInitializer(isWritten()))} will
+/// match \match{Foo(int) : foo_("A") { }}, but not \nomatch{Foo() { }}
 AST_MATCHER(CXXCtorInitializer, isWritten) {
   return Node.isWritten();
 }
@@ -4843,8 +6296,12 @@ AST_MATCHER(CXXCtorInitializer, isWritten) {
 ///     E() : B() {}
 ///   };
 /// \endcode
-/// cxxConstructorDecl(hasAnyConstructorInitializer(isBaseInitializer()))
-///   will match E(), but not match D(int).
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxConstructorDecl(hasAnyConstructorInitializer(isBaseInitializer()))}
+/// matches \match{E() : B() {}} and \match{D(int i) : I(i) {}}.
+/// The constructor of \c D is matched, because it implicitly has a constructor
+/// initializer for \c B .
 AST_MATCHER(CXXCtorInitializer, isBaseInitializer) {
   return Node.isBaseInitializer();
 }
@@ -4863,8 +6320,11 @@ AST_MATCHER(CXXCtorInitializer, isBaseInitializer) {
 ///     E() : B() {}
 ///   };
 /// \endcode
-/// cxxConstructorDecl(hasAnyConstructorInitializer(isMemberInitializer()))
-///   will match D(int), but not match E().
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxConstructorDecl(hasAnyConstructorInitializer(isMemberInitializer()))}
+///   will match \match{D(int i) : I(i) {}}, but not match \nomatch{E() : B()
+///   {}}.
 AST_MATCHER(CXXCtorInitializer, isMemberInitializer) {
   return Node.isMemberInitializer();
 }
@@ -4874,11 +6334,11 @@ AST_MATCHER(CXXCtorInitializer, isMemberInitializer) {
 ///
 /// Given
 /// \code
-///   void x(int, int, int) { int y; x(1, y, 42); }
+///   void x(int, int, int) { int y = 42; x(1, y, 42); }
 /// \endcode
-/// callExpr(hasAnyArgument(declRefExpr()))
-///   matches x(1, y, 42)
-/// with hasAnyArgument(...)
+/// The matcher
+/// \matcher{callExpr(hasAnyArgument(ignoringImplicit(declRefExpr())))} matches
+/// \match{x(1, y, 42)} with hasAnyArgument(...)
 ///   matching y
 ///
 /// For ObjectiveC, given
@@ -4886,8 +6346,10 @@ AST_MATCHER(CXXCtorInitializer, isMemberInitializer) {
 ///   @interface I - (void) f:(int) y; @end
 ///   void foo(I *i) { [i f:12]; }
 /// \endcode
-/// objcMessageExpr(hasAnyArgument(integerLiteral(equals(12))))
-///   matches [i f:12]
+/// \compile_args{-ObjC}
+/// The matcher
+/// \matcher{objcMessageExpr(hasAnyArgument(integerLiteral(equals(12))))}
+/// matches \match{[i f:12]}
 AST_POLYMORPHIC_MATCHER_P(hasAnyArgument,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(
                               CallExpr, CXXConstructExpr,
@@ -4916,8 +6378,12 @@ AST_POLYMORPHIC_MATCHER_P(hasAnyArgument,
 ///     auto g = [x = 1](){};
 ///   }
 /// \endcode
-/// In the matcher `lambdaExpr(hasAnyCapture(lambdaCapture()))`,
-/// `lambdaCapture()` matches `x` and `x=1`.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher
+/// \matcher{lambdaExpr(hasAnyCapture(lambdaCapture().bind("capture")))},
+/// matches \match{[x](){}} and \match{[x = 1](){}},
+/// with \matcher{type=sub$lambdaCapture()} matching
+/// \match{sub=capture$x} and \match{sub=capture$x = 1}.
 extern const internal::VariadicAllOfMatcher<LambdaCapture> lambdaCapture;
 
 /// Matches any capture in a lambda expression.
@@ -4929,9 +6395,10 @@ extern const internal::VariadicAllOfMatcher<LambdaCapture> lambdaCapture;
 ///     auto f = [=](){ return t; };
 ///   }
 /// \endcode
-/// lambdaExpr(hasAnyCapture(lambdaCapture())) and
-/// lambdaExpr(hasAnyCapture(lambdaCapture(refersToVarDecl(hasName("t")))))
-///   both match `[=](){ return t; }`.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{lambdaExpr(hasAnyCapture(lambdaCapture()))} and
+/// \matcher{lambdaExpr(hasAnyCapture(lambdaCapture(capturesVar(hasName("t")))))}
+///   both match \match{[=](){ return t; }}.
 AST_MATCHER_P(LambdaExpr, hasAnyCapture, internal::Matcher<LambdaCapture>,
               InnerMatcher) {
   for (const LambdaCapture &Capture : Node.captures()) {
@@ -4956,9 +6423,13 @@ AST_MATCHER_P(LambdaExpr, hasAnyCapture, internal::Matcher<LambdaCapture>,
 ///     auto g = [x = 1](){};
 ///   }
 /// \endcode
-/// In the matcher
-/// lambdaExpr(hasAnyCapture(lambdaCapture(capturesVar(hasName("x")))),
-/// capturesVar(hasName("x")) matches `x` and `x = 1`.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher
+/// \matcher{lambdaExpr(hasAnyCapture(
+///     lambdaCapture(capturesVar(hasName("x"))).bind("capture")))}
+/// matches \match{[x](){}} and \match{[x = 1](){}}, with
+/// \matcher{type=sub$lambdaCapture(capturesVar(hasName("x"))).bind("capture")}
+/// matching \match{sub=capture$x} and \match{sub=capture$x = 1}.
 AST_MATCHER_P(LambdaCapture, capturesVar, internal::Matcher<ValueDecl>,
               InnerMatcher) {
   if (!Node.capturesVariable())
@@ -4979,11 +6450,36 @@ AST_MATCHER_P(LambdaCapture, capturesVar, internal::Matcher<ValueDecl>,
 ///   }
 /// };
 /// \endcode
-/// lambdaExpr(hasAnyCapture(lambdaCapture(capturesThis())))
-///   matches `[this]() { return cc; }`.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher
+/// \matcher{lambdaExpr(hasAnyCapture(lambdaCapture(capturesThis())))}
+/// matches \match{[this]() { return cc; }}.
 AST_MATCHER(LambdaCapture, capturesThis) { return Node.capturesThis(); }
 
 /// Matches a constructor call expression which uses list initialization.
+///
+/// Given
+/// \code
+///   namespace std {
+///     template <typename T>
+///     class initializer_list {
+///       const T* begin;
+///       const T* end;
+///     };
+///   }
+///   template <typename T> class vector {
+///     public: vector(std::initializer_list<T>) {}
+///   };
+///
+///   vector<int> a({ 1, 2, 3 });
+///   vector<int> b = { 4, 5 };
+///   int c[] = { 6, 7 };
+///   struct pair { int x; int y; };
+///   pair d = { 8, 9 };
+/// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++11-or-later}
+/// The matcher \matcher{cxxConstructExpr(isListInitialization())}
+/// matches \match{{ 4, 5 }}.
 AST_MATCHER(CXXConstructExpr, isListInitialization) {
   return Node.isListInitialization();
 }
@@ -4994,12 +6490,16 @@ AST_MATCHER(CXXConstructExpr, isListInitialization) {
 /// Given
 /// \code
 /// void foo() {
-///   struct point { double x; double y; };
-///   point pt[2] = { { 1.0, 2.0 } };
+///   struct Foo {
+///     double x;
+///   };
+///   auto Val = Foo();
 /// }
 /// \endcode
-/// initListExpr(has(cxxConstructExpr(requiresZeroInitialization()))
-/// will match the implicit array filler for pt[1].
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxConstructExpr(requiresZeroInitialization())}
+/// matches \match{Foo()} because the \c x member has to be zero initialized.
 AST_MATCHER(CXXConstructExpr, requiresZeroInitialization) {
   return Node.requiresZeroInitialization();
 }
@@ -5011,17 +6511,20 @@ AST_MATCHER(CXXConstructExpr, requiresZeroInitialization) {
 /// \code
 ///   class X { void f(int x) {} };
 /// \endcode
-/// cxxMethodDecl(hasParameter(0, hasType(varDecl())))
-///   matches f(int x) {}
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxMethodDecl(hasParameter(0, hasType(asString("int"))))}
+/// matches \match{type=name$f}
 /// with hasParameter(...)
-///   matching int x
+/// matching int x.
 ///
 /// For ObjectiveC, given
 /// \code
 ///   @interface I - (void) f:(int) y; @end
 /// \endcode
-//
-/// the matcher objcMethodDecl(hasParameter(0, hasName("y")))
+/// \compile_args{-ObjC}
+///
+/// The matcher \matcher{objcMethodDecl(hasParameter(0, hasName("y")))}
 /// matches the declaration of method f with hasParameter
 /// matching y.
 AST_POLYMORPHIC_MATCHER_P2(hasParameter,
@@ -5046,9 +6549,13 @@ AST_POLYMORPHIC_MATCHER_P2(hasParameter,
 ///  int operator+(int);
 /// };
 /// \endcode
+/// \compile_args{-std=c++23-or-later}
 ///
-/// cxxMethodDecl(isExplicitObjectMemberFunction()) matches the first two
-/// methods but not the last two.
+/// The matcher \matcher{cxxMethodDecl(isExplicitObjectMemberFunction())}
+/// matches \match{int operator-(this A, int)} and
+/// \match{void fun(this A &&self)},
+/// but not \nomatch{static int operator()(int)} or
+/// \nomatch{int operator+(int)}.
 AST_MATCHER(CXXMethodDecl, isExplicitObjectMemberFunction) {
   return Node.isExplicitObjectMemberFunction();
 }
@@ -5059,14 +6566,16 @@ AST_MATCHER(CXXMethodDecl, isExplicitObjectMemberFunction) {
 /// \code
 ///   void f(int i);
 ///   int y;
-///   f(y);
+///   void foo() {
+///     f(y);
+///   }
 /// \endcode
-/// callExpr(
+/// The matcher \matcher{callExpr(
 ///   forEachArgumentWithParam(
 ///     declRefExpr(to(varDecl(hasName("y")))),
 ///     parmVarDecl(hasType(isInteger()))
-/// ))
-///   matches f(y);
+/// ))}
+///   matches \match{f(y)};
 /// with declRefExpr(...)
 ///   matching int y
 /// and parmVarDecl(...)
@@ -5119,17 +6628,18 @@ AST_POLYMORPHIC_MATCHER_P2(forEachArgumentWithParam,
 /// Given
 /// \code
 ///   void f(int i);
-///   int y;
-///   f(y);
-///   void (*f_ptr)(int) = f;
-///   f_ptr(y);
+///   void foo(int y) {
+///     f(y);
+///     void (*f_ptr)(int) = f;
+///     f_ptr(y);
+///   }
 /// \endcode
-/// callExpr(
+/// The matcher \matcher{callExpr(
 ///   forEachArgumentWithParamType(
 ///     declRefExpr(to(varDecl(hasName("y")))),
-///     qualType(isInteger()).bind("type)
-/// ))
-///   matches f(y) and f_ptr(y)
+///     qualType(isInteger()).bind("type")
+/// ))}
+///   matches \match{f(y)} and \match{f_ptr(y)}
 /// with declRefExpr(...)
 ///   matching int y
 /// and qualType(...)
@@ -5222,9 +6732,9 @@ AST_POLYMORPHIC_MATCHER_P2(forEachArgumentWithParamType,
 /// }
 /// \endcode
 ///
-/// ``parmVarDecl(isAtPosition(0))`` matches ``int a``.
-///
-/// ``parmVarDecl(isAtPosition(1))`` matches ``int b``.
+/// The matcher \matcher{parmVarDecl(isAtPosition(0))} matches
+/// \match{type=name$a}. The matcher \matcher{parmVarDecl(isAtPosition(1))}
+/// matches \match{type=name$b}.
 AST_MATCHER_P(ParmVarDecl, isAtPosition, unsigned, N) {
   const clang::DeclContext *Context = Node.getParentFunctionOrMethod();
 
@@ -5247,8 +6757,9 @@ AST_MATCHER_P(ParmVarDecl, isAtPosition, unsigned, N) {
 /// \code
 ///   class X { void f(int x, int y, int z) {} };
 /// \endcode
-/// cxxMethodDecl(hasAnyParameter(hasName("y")))
-///   matches f(int x, int y, int z) {}
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(hasAnyParameter(hasName("y")))}
+///   matches \match{type=name$f}
 /// with hasAnyParameter(...)
 ///   matching int y
 ///
@@ -5256,18 +6767,20 @@ AST_MATCHER_P(ParmVarDecl, isAtPosition, unsigned, N) {
 /// \code
 ///   @interface I - (void) f:(int) y; @end
 /// \endcode
-//
-/// the matcher objcMethodDecl(hasAnyParameter(hasName("y")))
-/// matches the declaration of method f with hasParameter
+/// \compile_args{-ObjC}
+///
+/// the matcher \matcher{objcMethodDecl(hasAnyParameter(hasName("y")))}
+///   matches the declaration of method f with hasParameter
 /// matching y.
 ///
 /// For blocks, given
 /// \code
 ///   b = ^(int y) { printf("%d", y) };
 /// \endcode
+/// \compile_args{-ObjC}
 ///
-/// the matcher blockDecl(hasAnyParameter(hasName("y")))
-/// matches the declaration of the block b with hasParameter
+/// the matcher \matcher{blockDecl(hasAnyParameter(hasName("y")))}
+///   matches the declaration of the block b with hasParameter
 /// matching y.
 AST_POLYMORPHIC_MATCHER_P(hasAnyParameter,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
@@ -5291,12 +6804,12 @@ AST_POLYMORPHIC_MATCHER_P(hasAnyParameter,
 ///   void j(int i);
 ///   void k(int x, int y, int z, ...);
 /// \endcode
-/// functionDecl(parameterCountIs(2))
-///   matches \c g and \c h
-/// functionProtoType(parameterCountIs(2))
-///   matches \c g and \c h
-/// functionProtoType(parameterCountIs(3))
-///   matches \c k
+/// The matcher \matcher{functionDecl(parameterCountIs(2))}
+/// matches \match{type=name$g} and \match{type=name$h}
+/// The matcher \matcher{functionProtoType(parameterCountIs(1))}
+/// matches the type \match{type=typestr;count=2$void (int)} of \c f and \c j.
+/// The matcher \matcher{functionProtoType(parameterCountIs(3))} matches the
+/// type \match{type=typestr$void (int, int, int, ...)} of \c k.
 AST_POLYMORPHIC_MATCHER_P(parameterCountIs,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                           FunctionProtoType),
@@ -5320,14 +6833,23 @@ AST_POLYMORPHIC_MATCHER_P(parameterCountIs,
 ///   template <typename T, typename U>
 ///   void f(T&& t, U&& u) {}
 ///
-///   bool B = false;
-///   f(R, B);
+///   void foo() {
+///     bool B = false;
+///     f(R, B);
+///   }
 /// \endcode
-/// templateSpecializationType(forEachTemplateArgument(isExpr(expr())))
-///   matches twice, with expr() matching 'R * 2' and 'R * 4'
-/// functionDecl(forEachTemplateArgument(refersToType(builtinType())))
-///   matches the specialization f<unsigned, bool> twice, for 'unsigned'
-///   and 'bool'
+/// \compile_args{-fno-delayed-template-parsing;-std=c++11-or-later}
+/// The matcher
+/// \matcher{templateSpecializationType(forEachTemplateArgument(isExpr(expr().bind("t_arg"))))}
+/// matches \match{type=typestr;count=2$Matrix<int, R * 2, R * 4>} twice, with
+/// \matcher{type=sub$expr()} matching \match{sub=t_arg$R * 2} and
+/// \match{sub=t_arg$R * 4}.
+/// The matcher
+/// \matcher{functionDecl(forEachTemplateArgument(refersToType(qualType().bind("type"))))}
+/// matches the specialization of \match{type=name;count=2$f} twice,
+/// with \matcher{type=sub$qualType()} matching
+/// \match{sub=type;type=typestr$unsigned} and
+/// \match{sub=type;type=typestr$bool}.
 AST_POLYMORPHIC_MATCHER_P(
     forEachTemplateArgument,
     AST_POLYMORPHIC_SUPPORTED_TYPES(ClassTemplateSpecializationDecl,
@@ -5358,21 +6880,22 @@ AST_POLYMORPHIC_MATCHER_P(
 ///   __attribute__((noreturn)) void b();
 ///   struct c { [[noreturn]] c(); };
 /// \endcode
-/// functionDecl(isNoReturn())
-///   matches all of those except
-/// \code
-///   void nope();
-/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{functionDecl(isNoReturn())}
+/// match \match{type=name$a}, \match{type=name$b}
+/// and \match{type=name$c}
+/// but do not match \nomatch{type=name$nope}
 AST_MATCHER(FunctionDecl, isNoReturn) { return Node.isNoReturn(); }
 
 /// Matches the return type of a function declaration.
 ///
-/// Given:
+/// Given
 /// \code
 ///   class X { int f() { return 1; } };
 /// \endcode
-/// cxxMethodDecl(returns(asString("int")))
-///   matches int f() { return 1; }
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(returns(asString("int")))}
+///   matches \match{type=name$f}
 AST_MATCHER_P(FunctionDecl, returns,
               internal::Matcher<QualType>, InnerMatcher) {
   return InnerMatcher.matches(Node.getReturnType(), Finder, Builder);
@@ -5380,7 +6903,7 @@ AST_MATCHER_P(FunctionDecl, returns,
 
 /// Matches extern "C" function or variable declarations.
 ///
-/// Given:
+/// Given
 /// \code
 ///   extern "C" void f() {}
 ///   extern "C" { void g() {} }
@@ -5389,10 +6912,14 @@ AST_MATCHER_P(FunctionDecl, returns,
 ///   extern "C" int y = 2;
 ///   int z = 3;
 /// \endcode
-/// functionDecl(isExternC())
-///   matches the declaration of f and g, but not the declaration of h.
-/// varDecl(isExternC())
-///   matches the declaration of x and y, but not the declaration of z.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{functionDecl(isExternC())}
+/// matches \match{type=name$f}
+/// and \match{type=name$g}.
+/// The matcher \matcher{varDecl(isExternC())}
+/// matches \match{type=name$x}
+/// and \match{type=name$y},
+/// but does not match \nomatch{type=name$z}.
 AST_POLYMORPHIC_MATCHER(isExternC, AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                                    VarDecl)) {
   return Node.isExternC();
@@ -5401,17 +6928,17 @@ AST_POLYMORPHIC_MATCHER(isExternC, AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
 /// Matches variable/function declarations that have "static" storage
 /// class specifier ("static" keyword) written in the source.
 ///
-/// Given:
+/// Given
 /// \code
 ///   static void f() {}
 ///   static int i = 0;
 ///   extern int j;
 ///   int k;
 /// \endcode
-/// functionDecl(isStaticStorageClass())
-///   matches the function declaration f.
-/// varDecl(isStaticStorageClass())
-///   matches the variable declaration i.
+/// The matcher \matcher{functionDecl(isStaticStorageClass())}
+///   matches \match{type=name$f}
+/// The matcher \matcher{varDecl(isStaticStorageClass())}
+///   matches \match{type=name$i}
 AST_POLYMORPHIC_MATCHER(isStaticStorageClass,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                         VarDecl)) {
@@ -5420,56 +6947,77 @@ AST_POLYMORPHIC_MATCHER(isStaticStorageClass,
 
 /// Matches deleted function declarations.
 ///
-/// Given:
+/// Given
 /// \code
 ///   void Func();
 ///   void DeletedFunc() = delete;
 /// \endcode
-/// functionDecl(isDeleted())
-///   matches the declaration of DeletedFunc, but not Func.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{functionDecl(isDeleted())}
+/// matches \match{type=name$DeletedFunc},
+/// but does not match \nomatch{type=name$Func}.
 AST_MATCHER(FunctionDecl, isDeleted) {
   return Node.isDeleted();
 }
 
 /// Matches defaulted function declarations.
 ///
-/// Given:
+/// Given
 /// \code
 ///   class A { ~A(); };
 ///   class B { ~B() = default; };
 /// \endcode
-/// functionDecl(isDefaulted())
-///   matches the declaration of ~B, but not ~A.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{functionDecl(isDefaulted())}
+///   matches \match{~B() = default},
+/// but does not match \nomatch{~A()}.
 AST_MATCHER(FunctionDecl, isDefaulted) {
   return Node.isDefaulted();
 }
 
 /// Matches weak function declarations.
 ///
-/// Given:
+/// Given
 /// \code
-///   void foo() __attribute__((__weakref__("__foo")));
-///   void bar();
+///   static void f();
+///   void g() __attribute__((weak));
 /// \endcode
-/// functionDecl(isWeak())
-///   matches the weak declaration "foo", but not "bar".
+/// The matcher \matcher{functionDecl(isWeak())}
+///   matches the weak declaration
+/// \match{void g() __attribute__((weak))},
+/// but does not match \nomatch{static void foo_v1()}.
 AST_MATCHER(FunctionDecl, isWeak) { return Node.isWeak(); }
 
 /// Matches functions that have a dynamic exception specification.
 ///
-/// Given:
+/// Given
 /// \code
-///   void f();
-///   void g() noexcept;
-///   void h() noexcept(true);
-///   void i() noexcept(false);
-///   void j() throw();
-///   void k() throw(int);
-///   void l() throw(...);
-/// \endcode
-/// functionDecl(hasDynamicExceptionSpec()) and
-///   functionProtoType(hasDynamicExceptionSpec())
-///   match the declarations of j, k, and l, but not f, g, h, or i.
+///   void f(int);
+///   void g(int) noexcept;
+///   void h(int) noexcept(true);
+///   void i(int) noexcept(false);
+///   void j(int) throw();
+///   void k(int) throw(int);
+///   void l(int) throw(...);
+/// \endcode
+/// \compile_args{-std=c++11-14}
+/// The matcher \matcher{functionDecl(hasDynamicExceptionSpec())}
+/// matches the declarations \match{void j(int) throw()},
+/// \match{void k(int) throw(int)}
+/// and \match{void l(int) throw(...)},
+/// but does not match \nomatch{void f(int)}, \nomatch{void g(int) noexcept},
+/// \nomatch{void h(int) noexcept(true)}
+/// or \nomatch{void i(int) noexcept(true)}.
+/// The matcher
+/// \matcher{functionProtoType(hasDynamicExceptionSpec())} matches
+/// the type \match{type=typestr$void (int) throw()} of \c j ,
+/// the type \match{type=typestr$void (int) throw(int)} of \c k and
+/// the type \match{type=typestr$void (int) throw(...)} of \c l .
+/// It does not match
+/// the type \nomatch{type=typestr$void (int) noexcept} of \c f ,
+/// the type \nomatch{type=typestr$void (int) noexcept} of \c g ,
+/// the type \nomatch{type=typestr$void (int) noexcept(int)} of \c h or
+/// the type \nomatch{type=typestr$void (int) noexcept(...)} of \c i .
 AST_POLYMORPHIC_MATCHER(hasDynamicExceptionSpec,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                         FunctionProtoType)) {
@@ -5480,16 +7028,29 @@ AST_POLYMORPHIC_MATCHER(hasDynamicExceptionSpec,
 
 /// Matches functions that have a non-throwing exception specification.
 ///
-/// Given:
+/// Given
 /// \code
-///   void f();
-///   void g() noexcept;
-///   void h() throw();
-///   void i() throw(int);
-///   void j() noexcept(false);
+///   void f(int);
+///   void g(int) noexcept;
+///   void h(int) noexcept(false);
+///   void i(int) throw();
+///   void j(int) throw(int);
 /// \endcode
-/// functionDecl(isNoThrow()) and functionProtoType(isNoThrow())
-///   match the declarations of g, and h, but not f, i or j.
+/// \compile_args{-std=c++11-14}
+/// The matcher \matcher{functionDecl(isNoThrow())}
+/// matches the declaration \match{void g(int) noexcept}
+/// and \match{void i(int) throw()},
+/// but does not match \nomatch{void f(int)},
+/// \nomatch{void h(int) noexcept(false)}
+/// or \nomatch{void j(int) throw(int)}.
+/// The matcher
+/// \matcher{functionProtoType(isNoThrow())}
+/// matches the type \match{type=typestr$void (int) throw()} of \c i
+/// and the type \match{type=typestr$void (int) noexcept} of \c g,
+/// but does not match
+/// the type \nomatch{type=typestr$void (int)} of \c f ,
+/// the type \nomatch{type=typestr$void (int) noexcept(false)} of \c h or
+/// the type \nomatch{type=typestr$void (int) throw(int)} of \c j .
 AST_POLYMORPHIC_MATCHER(isNoThrow,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                         FunctionProtoType)) {
@@ -5511,17 +7072,20 @@ AST_POLYMORPHIC_MATCHER(isNoThrow,
 /// Matches consteval function declarations and if consteval/if ! consteval
 /// statements.
 ///
-/// Given:
+/// Given
 /// \code
 ///   consteval int a();
 ///   void b() { if consteval {} }
 ///   void c() { if ! consteval {} }
 ///   void d() { if ! consteval {} else {} }
 /// \endcode
-/// functionDecl(isConsteval())
-///   matches the declaration of "int a()".
-/// ifStmt(isConsteval())
-///   matches the if statement in "void b()", "void c()", "void d()".
+/// \compile_args{-std=c++23-or-later}
+/// The matcher \matcher{functionDecl(isConsteval())}
+/// matches \match{type=name$a}.
+/// The matcher \matcher{ifStmt(isConsteval())}
+/// matches the if statements
+/// \match{if consteval {}}, \match{if ! consteval {}} and
+/// \match{if ! consteval {} else {}}.
 AST_POLYMORPHIC_MATCHER(isConsteval,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl, IfStmt)) {
   return Node.isConsteval();
@@ -5530,18 +7094,19 @@ AST_POLYMORPHIC_MATCHER(isConsteval,
 /// Matches constexpr variable and function declarations,
 ///        and if constexpr.
 ///
-/// Given:
+/// Given
 /// \code
 ///   constexpr int foo = 42;
 ///   constexpr int bar();
 ///   void baz() { if constexpr(1 > 0) {} }
 /// \endcode
-/// varDecl(isConstexpr())
-///   matches the declaration of foo.
-/// functionDecl(isConstexpr())
-///   matches the declaration of bar.
-/// ifStmt(isConstexpr())
-///   matches the if statement in baz.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{varDecl(isConstexpr())}
+/// matches \match{type=name$foo}.
+/// The matcher \matcher{functionDecl(isConstexpr())}
+/// matches \match{type=name$bar}.
+/// The matcher \matcher{ifStmt(isConstexpr())}
+/// matches \match{if constexpr(1 > 0) {}}.
 AST_POLYMORPHIC_MATCHER(isConstexpr,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(VarDecl,
                                                         FunctionDecl,
@@ -5551,15 +7116,19 @@ AST_POLYMORPHIC_MATCHER(isConstexpr,
 
 /// Matches constinit variable declarations.
 ///
-/// Given:
+/// Given
 /// \code
 ///   constinit int foo = 42;
 ///   constinit const char* bar = "bar";
 ///   int baz = 42;
 ///   [[clang::require_constant_initialization]] int xyz = 42;
 /// \endcode
-/// varDecl(isConstinit())
-///   matches the declaration of `foo` and `bar`, but not `baz` and `xyz`.
+/// \compile_args{-std=c++20-or-later}
+/// The matcher \matcher{varDecl(isConstinit())}
+/// matches the declaration of \match{type=name$foo}
+/// and \match{type=name$bar},
+/// but does not match \nomatch{type=name$baz} or
+/// \nomatch{xyz}.
 AST_MATCHER(VarDecl, isConstinit) {
   if (const auto *CIA = Node.getAttr<ConstInitAttr>())
     return CIA->isConstinit();
@@ -5568,8 +7137,11 @@ AST_MATCHER(VarDecl, isConstinit) {
 
 /// Matches selection statements with initializer.
 ///
-/// Given:
+/// Given
 /// \code
+///  struct vec { int* begin(); int* end(); };
+///  int foobar();
+///  vec& get_range();
 ///  void foo() {
 ///    if (int i = foobar(); i > 0) {}
 ///    switch (int i = foobar(); i) {}
@@ -5581,12 +7153,17 @@ AST_MATCHER(VarDecl, isConstinit) {
 ///    for (auto& x : get_range()) {}
 ///  }
 /// \endcode
-/// ifStmt(hasInitStatement(anything()))
-///   matches the if statement in foo but not in bar.
-/// switchStmt(hasInitStatement(anything()))
-///   matches the switch statement in foo but not in bar.
-/// cxxForRangeStmt(hasInitStatement(anything()))
-///   matches the range for statement in foo but not in bar.
+/// \compile_args{-std=c++20-or-later}
+/// The matcher \matcher{ifStmt(hasInitStatement(anything()))}
+///   matches the if statement \match{if (int i = foobar(); i > 0) {}}
+///   in foo but not \nomatch{if (foobar() > 0) {}} in bar.
+/// The matcher \matcher{switchStmt(hasInitStatement(anything()))}
+///   matches the switch statement \match{switch (int i = foobar(); i) {}}
+///   in foo but not \nomatch{switch (foobar()) {}} in bar.
+/// The matcher \matcher{cxxForRangeStmt(hasInitStatement(anything()))}
+///   matches the range for statement
+///   \match{for (auto& a = get_range(); auto& x : a) {}} in foo
+///   but not \nomatch{for (auto& x : get_range()) {}} in bar.
 AST_POLYMORPHIC_MATCHER_P(hasInitStatement,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(IfStmt, SwitchStmt,
                                                           CXXForRangeStmt),
@@ -5598,10 +7175,15 @@ AST_POLYMORPHIC_MATCHER_P(hasInitStatement,
 /// Matches the condition expression of an if statement, for loop,
 /// switch statement or conditional operator.
 ///
-/// Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true))))
+/// Given
 /// \code
+/// void foo() {
 ///   if (true) {}
+/// }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{ifStmt(hasCondition(cxxBoolLiteral(equals(true))))}
+/// \match{if (true) {}}
 AST_POLYMORPHIC_MATCHER_P(
     hasCondition,
     AST_POLYMORPHIC_SUPPORTED_TYPES(IfStmt, ForStmt, WhileStmt, DoStmt,
@@ -5614,11 +7196,15 @@ AST_POLYMORPHIC_MATCHER_P(
 
 /// Matches the then-statement of an if statement.
 ///
-/// Examples matches the if statement
-///   (matcher = ifStmt(hasThen(cxxBoolLiteral(equals(true)))))
+/// Given
 /// \code
+/// void foo() {
 ///   if (false) true; else false;
+/// }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{ifStmt(hasThen(cxxBoolLiteral(equals(true))))}
+/// \match{if (false) true; else false}
 AST_MATCHER_P(IfStmt, hasThen, internal::Matcher<Stmt>, InnerMatcher) {
   const Stmt *const Then = Node.getThen();
   return (Then != nullptr && InnerMatcher.matches(*Then, Finder, Builder));
@@ -5626,11 +7212,15 @@ AST_MATCHER_P(IfStmt, hasThen, internal::Matcher<Stmt>, InnerMatcher) {
 
 /// Matches the else-statement of an if statement.
 ///
-/// Examples matches the if statement
-///   (matcher = ifStmt(hasElse(cxxBoolLiteral(equals(true)))))
+/// Given
 /// \code
+/// void foo() {
 ///   if (false) false; else true;
+/// }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{ifStmt(hasElse(cxxBoolLiteral(equals(true))))}
+/// \match{if (false) false; else true}
 AST_MATCHER_P(IfStmt, hasElse, internal::Matcher<Stmt>, InnerMatcher) {
   const Stmt *const Else = Node.getElse();
   return (Else != nullptr && InnerMatcher.matches(*Else, Finder, Builder));
@@ -5644,10 +7234,11 @@ AST_MATCHER_P(IfStmt, hasElse, internal::Matcher<Stmt>, InnerMatcher) {
 /// \code
 ///   class X { int a; int b; };
 /// \endcode
-/// cxxRecordDecl(
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(
 ///     has(fieldDecl(hasName("a"), hasType(type().bind("t")))),
-///     has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))
-///   matches the class \c X, as \c a and \c b have the same type.
+///     has(fieldDecl(hasName("b"), hasType(type(equalsBoundNode("t"))))))}
+///   matches \match{type=name$X}, as \c a and \c b have the same type.
 ///
 /// Note that when multiple matches are involved via \c forEach* matchers,
 /// \c equalsBoundNodes acts as a filter.
@@ -5677,14 +7268,19 @@ AST_POLYMORPHIC_MATCHER_P(equalsBoundNode,
 ///
 /// Given
 /// \code
+/// struct A {};
+/// A* GetAPointer();
+/// void foo() {
 ///   if (A* a = GetAPointer()) {}
+/// }
 /// \endcode
-/// hasConditionVariableStatement(...)
-///   matches 'A* a = GetAPointer()'.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{ifStmt(hasConditionVariableStatement(declStmt()))}
+/// \match{if (A* a = GetAPointer()) {}}
 AST_MATCHER_P(IfStmt, hasConditionVariableStatement,
               internal::Matcher<DeclStmt>, InnerMatcher) {
-  const DeclStmt* const DeclarationStatement =
-    Node.getConditionVariableDeclStmt();
+  const DeclStmt *const DeclarationStatement =
+      Node.getConditionVariableDeclStmt();
   return DeclarationStatement != nullptr &&
          InnerMatcher.matches(*DeclarationStatement, Finder, Builder);
 }
@@ -5696,11 +7292,11 @@ AST_MATCHER_P(IfStmt, hasConditionVariableStatement,
 ///   int i[5];
 ///   void f() { i[1] = 42; }
 /// \endcode
-/// arraySubscriptExpression(hasIndex(integerLiteral()))
-///   matches \c i[1] with the \c integerLiteral() matching \c 1
-AST_MATCHER_P(ArraySubscriptExpr, hasIndex,
-              internal::Matcher<Expr>, InnerMatcher) {
-  if (const Expr* Expression = Node.getIdx())
+/// The matcher \matcher{arraySubscriptExpr(hasIndex(integerLiteral()))}
+///   matches \match{i[1]} with the \c integerLiteral() matching \c 1
+AST_MATCHER_P(ArraySubscriptExpr, hasIndex, internal::Matcher<Expr>,
+              InnerMatcher) {
+  if (const Expr *Expression = Node.getIdx())
     return InnerMatcher.matches(*Expression, Finder, Builder);
   return false;
 }
@@ -5712,9 +7308,9 @@ AST_MATCHER_P(ArraySubscriptExpr, hasIndex,
 ///   int i[5];
 ///   void f() { i[1] = 42; }
 /// \endcode
-/// arraySubscriptExpression(hasBase(implicitCastExpr(
-///     hasSourceExpression(declRefExpr()))))
-///   matches \c i[1] with the \c declRefExpr() matching \c i
+/// The matcher \matcher{arraySubscriptExpr(hasBase(implicitCastExpr(
+///     hasSourceExpression(declRefExpr()))))}
+///   matches \match{i[1]} with the \c declRefExpr() matching \c i
 AST_MATCHER_P(ArraySubscriptExpr, hasBase,
               internal::Matcher<Expr>, InnerMatcher) {
   if (const Expr* Expression = Node.getBase())
@@ -5729,23 +7325,25 @@ AST_MATCHER_P(ArraySubscriptExpr, hasBase,
 ///
 /// Given
 /// \code
+/// void foo() {
 ///   for (;;) {}
+/// }
 /// \endcode
-/// forStmt(hasBody(compoundStmt()))
-///   matches 'for (;;) {}'
-/// with compoundStmt()
-///   matching '{}'
+/// The matcher \matcher{forStmt(hasBody(compoundStmt().bind("body")))}
+/// matches \match{for (;;) {}}
+/// with \matcher{type=sub$compoundStmt()}
+///   matching \match{sub=body${}}
 ///
 /// Given
 /// \code
 ///   void f();
 ///   void f() {}
 /// \endcode
-/// functionDecl(hasBody(compoundStmt()))
-///   matches 'void f() {}'
-/// with compoundStmt()
-///   matching '{}'
-///   but does not match 'void f();'
+/// The matcher \matcher{functionDecl(hasBody(compoundStmt().bind("compound")))}
+/// \match{type=name$f}
+/// with \matcher{type=sub$compoundStmt()}
+/// matching \match{sub=compound${}}
+/// but does not match \nomatch{void f();}
 AST_POLYMORPHIC_MATCHER_P(
     hasBody,
     AST_POLYMORPHIC_SUPPORTED_TYPES(DoStmt, ForStmt, WhileStmt, CXXForRangeStmt,
@@ -5768,31 +7366,30 @@ AST_POLYMORPHIC_MATCHER_P(
 ///   void f() {}
 ///   void g();
 /// \endcode
-/// functionDecl(hasAnyBody(compoundStmt()))
-///   matches both 'void f();'
-///   and 'void f() {}'
-/// with compoundStmt()
-///   matching '{}'
-///   but does not match 'void g();'
-AST_MATCHER_P(FunctionDecl, hasAnyBody,
-              internal::Matcher<Stmt>, InnerMatcher) {
+/// The matcher \matcher{functionDecl(hasAnyBody(compoundStmt()))}
+///   matches \match{type=name$f}
+///   and \match{type=name$f}
+/// with \matcher{compoundStmt()}
+///   matching \match{{}}
+///   but does not match \nomatch{void g();}
+AST_MATCHER_P(FunctionDecl, hasAnyBody, internal::Matcher<Stmt>, InnerMatcher) {
   const Stmt *const Statement = Node.getBody();
   return (Statement != nullptr &&
           InnerMatcher.matches(*Statement, Finder, Builder));
 }
 
-
 /// Matches compound statements where at least one substatement matches
 /// a given matcher. Also matches StmtExprs that have CompoundStmt as children.
 ///
 /// Given
 /// \code
-///   { {}; 1+2; }
+/// void foo() { { {}; 1+2; } }
 /// \endcode
-/// hasAnySubstatement(compoundStmt())
-///   matches '{ {}; 1+2; }'
-/// with compoundStmt()
-///   matching '{}'
+/// The matcher
+/// \matcher{compoundStmt(hasAnySubstatement(compoundStmt().bind("compound")))}
+/// \match{{ {}; 1+2; }} and \match{{ { {}; 1+2; } }}
+/// with \matcher{type=sub$compoundStmt()}
+/// matching \match{sub=compound${}} and \match{sub=compound${ {}; 1+2; }}.
 AST_POLYMORPHIC_MATCHER_P(hasAnySubstatement,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(CompoundStmt,
                                                           StmtExpr),
@@ -5808,10 +7405,12 @@ AST_POLYMORPHIC_MATCHER_P(hasAnySubstatement,
 ///
 /// Example: Given
 /// \code
+/// void foo() {
 ///   { for (;;) {} }
+/// }
 /// \endcode
-/// compoundStmt(statementCountIs(0)))
-///   matches '{}'
+/// The matcher \matcher{compoundStmt(statementCountIs(0))}
+/// \match{{}}
 ///   but does not match the outer compound statement.
 AST_MATCHER_P(CompoundStmt, statementCountIs, unsigned, N) {
   return Node.size() == N;
@@ -5821,24 +7420,31 @@ AST_MATCHER_P(CompoundStmt, statementCountIs, unsigned, N) {
 ///
 /// Given
 /// \code
+/// void f(char, bool, double, int);
+/// void foo() {
 ///   f('\0', false, 3.14, 42);
+/// }
 /// \endcode
-/// characterLiteral(equals(0))
-///   matches '\0'
-/// cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
-///   match false
-/// floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
-///   match 3.14
-/// integerLiteral(equals(42))
-///   matches 42
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{characterLiteral(equals(0U))} matches \match{'\0'}.
+/// The matchers \matcher{cxxBoolLiteral(equals(false))} and
+/// \matcher{cxxBoolLiteral(equals(0))} match \match{false}.
+/// The matcher \matcher{floatLiteral(equals(3.14))} matches \match{3.14}.
+/// The matcher \matcher{integerLiteral(equals(42))} matches \match{42}.
 ///
 /// Note that you cannot directly match a negative numeric literal because the
 /// minus sign is not part of the literal: It is a unary operator whose operand
 /// is the positive numeric literal. Instead, you must use a unaryOperator()
 /// matcher to match the minus sign:
 ///
-/// unaryOperator(hasOperatorName("-"),
-///               hasUnaryOperand(integerLiteral(equals(13))))
+/// Given
+/// \code
+///   int val = -1;
+/// \endcode
+///
+/// The matcher \matcher{unaryOperator(hasOperatorName("-"),
+///               hasUnaryOperand(integerLiteral(equals(1))))}
+/// matches \match{-1}.
 ///
 /// Usable as: Matcher<CharacterLiteral>, Matcher<CXXBoolLiteralExpr>,
 ///            Matcher<FloatingLiteral>, Matcher<IntegerLiteral>
@@ -5882,19 +7488,26 @@ AST_POLYMORPHIC_MATCHER_P_OVERLOAD(equals,
 /// Matches the operator Name of operator expressions and fold expressions
 /// (binary or unary).
 ///
-/// Example matches a || b (matcher = binaryOperator(hasOperatorName("||")))
+/// Given
 /// \code
-///   !(a || b)
+//// void foo(bool a, bool b) {
+///   !(a || b);
+///  }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{binaryOperator(hasOperatorName("||"))}
+/// matches \match{a || b}
 ///
-/// Example matches `(0 + ... + args)`
-///     (matcher = cxxFoldExpr(hasOperatorName("+")))
+/// Given
 /// \code
 ///   template <typename... Args>
 ///   auto sum(Args... args) {
 ///       return (0 + ... + args);
 ///   }
 /// \endcode
+/// \compile_args{-std=c++17-or-later}
+/// The matcher \matcher{cxxFoldExpr(hasOperatorName("+"))}
+///  matches \match{(0 + ... + args)}.
 AST_POLYMORPHIC_MATCHER_P(
     hasOperatorName,
     AST_POLYMORPHIC_SUPPORTED_TYPES(BinaryOperator, CXXOperatorCallExpr,
@@ -5909,9 +7522,28 @@ AST_POLYMORPHIC_MATCHER_P(
 /// Matches operator expressions (binary or unary) that have any of the
 /// specified names.
 ///
-///    hasAnyOperatorName("+", "-")
-///  Is equivalent to
-///    anyOf(hasOperatorName("+"), hasOperatorName("-"))
+/// It provides a compact way of writing if an operator has any of the specified
+/// names:
+/// The matcher
+///    \c hasAnyOperatorName("+", "-")
+/// Is equivalent to
+///    \c{anyOf(hasOperatorName("+"), hasOperatorName("-"))}
+///
+/// Given
+/// \code
+//// void foo(bool a, bool b) {
+///   !(a || b);
+///  }
+///
+//// void bar(bool a, bool b) {
+///   a && b;
+///  }
+/// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{binaryOperator(hasAnyOperatorName("||", "&&"))}
+/// matches \match{a || b} and \match{a && b}.
+/// The matcher \matcher{unaryOperator(hasAnyOperatorName("-", "!"))}
+/// matches \match{!(a || b)}.
 extern const internal::VariadicFunction<
     internal::PolymorphicMatcher<internal::HasAnyOperatorNameMatcher,
                                  AST_POLYMORPHIC_SUPPORTED_TYPES(
@@ -5923,18 +7555,24 @@ extern const internal::VariadicFunction<
 
 /// Matches all kinds of assignment operators.
 ///
-/// Example 1: matches a += b (matcher = binaryOperator(isAssignmentOperator()))
+/// Given
 /// \code
+/// void foo(int a, int b) {
 ///   if (a == b)
 ///     a += b;
+/// }
 /// \endcode
+/// The matcher \matcher{binaryOperator(isAssignmentOperator())}
+/// matches \match{a += b}.
 ///
-/// Example 2: matches s1 = s2
-///            (matcher = cxxOperatorCallExpr(isAssignmentOperator()))
+/// Given
 /// \code
 ///   struct S { S& operator=(const S&); };
 ///   void x() { S s1, s2; s1 = s2; }
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxOperatorCallExpr(isAssignmentOperator())}
+/// matches \match{s1 = s2}.
 AST_POLYMORPHIC_MATCHER(
     isAssignmentOperator,
     AST_POLYMORPHIC_SUPPORTED_TYPES(BinaryOperator, CXXOperatorCallExpr,
@@ -5944,18 +7582,24 @@ AST_POLYMORPHIC_MATCHER(
 
 /// Matches comparison operators.
 ///
-/// Example 1: matches a == b (matcher = binaryOperator(isComparisonOperator()))
+/// Given
 /// \code
+/// void foo(int a, int b) {
 ///   if (a == b)
 ///     a += b;
+/// }
 /// \endcode
+/// The matcher \matcher{binaryOperator(isComparisonOperator())}
+/// matches \match{a == b}
 ///
-/// Example 2: matches s1 < s2
-///            (matcher = cxxOperatorCallExpr(isComparisonOperator()))
+/// Given
 /// \code
 ///   struct S { bool operator<(const S& other); };
 ///   void x(S s1, S s2) { bool b1 = s1 < s2; }
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxOperatorCallExpr(isComparisonOperator())}
+/// matches \match{s1 < s2}
 AST_POLYMORPHIC_MATCHER(
     isComparisonOperator,
     AST_POLYMORPHIC_SUPPORTED_TYPES(BinaryOperator, CXXOperatorCallExpr,
@@ -5965,10 +7609,17 @@ AST_POLYMORPHIC_MATCHER(
 
 /// Matches the left hand side of binary operator expressions.
 ///
-/// Example matches a (matcher = binaryOperator(hasLHS()))
+/// Given
 /// \code
-///   a || b
+/// void foo(bool a, bool b) {
+///   a || b;
+/// }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{binaryOperator(hasLHS(expr().bind("lhs")))}
+/// matches \match{a || b},
+/// with \matcher{type=sub$expr()}
+/// matching \match{sub=lhs$a}.
 AST_POLYMORPHIC_MATCHER_P(
     hasLHS,
     AST_POLYMORPHIC_SUPPORTED_TYPES(BinaryOperator, CXXOperatorCallExpr,
@@ -5982,10 +7633,17 @@ AST_POLYMORPHIC_MATCHER_P(
 
 /// Matches the right hand side of binary operator expressions.
 ///
-/// Example matches b (matcher = binaryOperator(hasRHS()))
+/// Given
 /// \code
-///   a || b
+/// void foo(bool a, bool b) {
+///   a || b;
+/// }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{binaryOperator(hasRHS(expr().bind("rhs")))}
+/// matches \match{a || b},
+/// with \matcher{type=sub$expr()}
+/// matching \match{sub=rhs$b}.
 AST_POLYMORPHIC_MATCHER_P(
     hasRHS,
     AST_POLYMORPHIC_SUPPORTED_TYPES(BinaryOperator, CXXOperatorCallExpr,
@@ -5999,6 +7657,32 @@ AST_POLYMORPHIC_MATCHER_P(
 
 /// Matches if either the left hand side or the right hand side of a
 /// binary operator or fold expression matches.
+///
+/// Given
+/// \code
+///   struct S {};
+///   bool operator ==(const S&, const S&);
+///
+///   void f(int a, const S&lhs, const S&rhs) {
+///       a + 0;
+///       lhs == rhs;
+///       lhs != rhs;
+///   }
+///
+///   template <typename ...Ts>
+///   auto sum(Ts... args) {
+///     return (0 + ... + args);
+///   }
+/// \endcode
+/// \compile_args{-std=c++20-or-later}
+///
+/// The matcher \matcher{binaryOperator(hasEitherOperand(integerLiteral()))}
+/// matches \match{a + 0}.
+/// The matcher \matcher{cxxOperatorCallExpr(hasEitherOperand(declRefExpr(to(
+/// parmVarDecl(hasName("lhs"))))))} matches \match{lhs == rhs} and
+/// \match{lhs != rhs}.
+/// The matcher \matcher{cxxFoldExpr(hasEitherOperand(integerLiteral()))}
+/// matches \match{(0 + ... + args)}.
 AST_POLYMORPHIC_MATCHER_P(
     hasEitherOperand,
     AST_POLYMORPHIC_SUPPORTED_TYPES(BinaryOperator, CXXOperatorCallExpr,
@@ -6012,14 +7696,20 @@ AST_POLYMORPHIC_MATCHER_P(
 /// Matches if both matchers match with opposite sides of the binary operator
 /// or fold expression.
 ///
-/// Example matcher = binaryOperator(hasOperands(integerLiteral(equals(1),
-///                                              integerLiteral(equals(2)))
+/// Given
 /// \code
-///   1 + 2 // Match
-///   2 + 1 // Match
-///   1 + 1 // No match
-///   2 + 2 // No match
+/// void foo() {
+///   1 + 2; // Match
+///   2 + 1; // Match
+///   1 + 1; // No match
+///   2 + 2; // No match
+/// }
 /// \endcode
+/// The matcher \matcher{binaryOperator(hasOperands(integerLiteral(equals(1)),
+///                                             integerLiteral(equals(2))))}
+/// matches \match{1 + 2} and \match{2 + 1},
+/// but does not match \nomatch{1 + 1}
+/// or \nomatch{2 + 2}.
 AST_POLYMORPHIC_MATCHER_P2(
     hasOperands,
     AST_POLYMORPHIC_SUPPORTED_TYPES(BinaryOperator, CXXOperatorCallExpr,
@@ -6033,11 +7723,15 @@ AST_POLYMORPHIC_MATCHER_P2(
 
 /// Matches if the operand of a unary operator matches.
 ///
-/// Example matches true (matcher = hasUnaryOperand(
-///                                   cxxBoolLiteral(equals(true))))
 /// \code
-///   !true
+/// void foo() {
+///   !true;
+/// }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher
+/// \matcher{unaryOperator(hasUnaryOperand(cxxBoolLiteral(equals(true))))}
+/// matches \match{!true}.
 AST_POLYMORPHIC_MATCHER_P(hasUnaryOperand,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(UnaryOperator,
                                                           CXXOperatorCallExpr),
@@ -6050,18 +7744,27 @@ AST_POLYMORPHIC_MATCHER_P(hasUnaryOperand,
 /// Matches if the cast's source expression
 /// or opaque value's source expression matches the given matcher.
 ///
-/// Example 1: matches "a string"
-/// (matcher = castExpr(hasSourceExpression(cxxConstructExpr())))
+/// Given
 /// \code
-/// class URL { URL(string); };
-/// URL url = "a string";
+///  struct URL { URL(const char*); };
+///  URL url = "a string";
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{castExpr(hasSourceExpression(cxxConstructExpr()))}
+/// matches \match{"a string"}.
 ///
-/// Example 2: matches 'b' (matcher =
-/// opaqueValueExpr(hasSourceExpression(implicitCastExpr(declRefExpr())))
+/// Given
 /// \code
-/// int a = b ?: 1;
+/// void foo(bool b) {
+///   int a = b ?: 1;
+/// }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher
+/// \matcher{opaqueValueExpr(hasSourceExpression(
+///               implicitCastExpr(has(
+///                 implicitCastExpr(has(declRefExpr()))))))}
+/// matches \match{count=2$b} twice, for the conditiona and the true expression.
 AST_POLYMORPHIC_MATCHER_P(hasSourceExpression,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(CastExpr,
                                                           OpaqueValueExpr),
@@ -6074,11 +7777,12 @@ AST_POLYMORPHIC_MATCHER_P(hasSourceExpression,
 
 /// Matches casts that has a given cast kind.
 ///
-/// Example: matches the implicit cast around \c 0
-/// (matcher = castExpr(hasCastKind(CK_NullToPointer)))
+/// Given
 /// \code
 ///   int *p = 0;
 /// \endcode
+/// The matcher \matcher{castExpr(hasCastKind(CK_NullToPointer))}
+/// matches the implicit cast around \match{0}
 ///
 /// If the matcher is use from clang-query, CastKind parameter
 /// should be passed as a quoted string. e.g., hasCastKind("CK_NullToPointer").
@@ -6090,14 +7794,30 @@ AST_MATCHER_P(CastExpr, hasCastKind, CastKind, Kind) {
 ///
 /// (Note: Clang's AST refers to other conversions as "casts" too, and calls
 /// actual casts "explicit" casts.)
-AST_MATCHER_P(ExplicitCastExpr, hasDestinationType,
-              internal::Matcher<QualType>, InnerMatcher) {
+///
+/// \code
+///   unsigned int a = (unsigned int)0;
+/// \endcode
+///
+/// The matcher \matcher{explicitCastExpr(hasDestinationType(
+/// qualType(isUnsignedInteger())))} matches \match{(unsigned int)0}.
+AST_MATCHER_P(ExplicitCastExpr, hasDestinationType, internal::Matcher<QualType>,
+              InnerMatcher) {
   const QualType NodeType = Node.getTypeAsWritten();
   return InnerMatcher.matches(NodeType, Finder, Builder);
 }
 
 /// Matches implicit casts whose destination type matches a given
 /// matcher.
+///
+/// Given
+/// \code
+///   unsigned int a = 0;
+/// \endcode
+///
+/// The matcher
+/// \matcher{implicitCastExpr(hasImplicitDestinationType(
+/// qualType(isUnsignedInteger())))} matches \match{0}.
 AST_MATCHER_P(ImplicitCastExpr, hasImplicitDestinationType,
               internal::Matcher<QualType>, InnerMatcher) {
   return InnerMatcher.matches(Node.getType(), Finder, Builder);
@@ -6110,47 +7830,70 @@ AST_MATCHER_P(ImplicitCastExpr, hasImplicitDestinationType,
 ///   struct S {};
 ///   class C {};
 ///   union U {};
-///   enum E {};
-/// \endcode
+///   enum E { Ok };
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{tagDecl(isStruct())}
+/// matches \match{type=typestr;count=2$struct S},
+/// but does not match \nomatch{type=typestr;count=2$class C},
+/// \nomatch{type=typestr;count=2$union U}
+/// or \nomatch{type=typestr;count=2$enum E}.
 AST_MATCHER(TagDecl, isStruct) {
   return Node.isStruct();
 }
 
 /// Matches TagDecl object that are spelled with "union."
 ///
-/// Example matches U, but not C, S or E.
+/// Given
 /// \code
 ///   struct S {};
 ///   class C {};
 ///   union U {};
-///   enum E {};
-/// \endcode
+///   enum E { Ok };
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{tagDecl(isUnion())}
+/// matches \match{type=typestr;count=2$union U},
+/// does not match \nomatch{type=typestr;count=2$struct S},
+/// \nomatch{type=typestr;count=2$class C}
+/// or \nomatch{type=typestr;count=2$enum E}.
 AST_MATCHER(TagDecl, isUnion) {
   return Node.isUnion();
 }
 
 /// Matches TagDecl object that are spelled with "class."
 ///
-/// Example matches C, but not S, U or E.
+/// Given
 /// \code
 ///   struct S {};
 ///   class C {};
 ///   union U {};
-///   enum E {};
-/// \endcode
+///   enum E { Ok };
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{tagDecl(isClass())}
+/// matches \match{type=typestr;count=2$class C},
+/// but does not match \nomatch{type=typestr;count=2$struct S},
+/// \nomatch{type=typestr;count=2$union U}
+/// or \nomatch{type=typestr;count=2$enum E}.
 AST_MATCHER(TagDecl, isClass) {
   return Node.isClass();
 }
 
 /// Matches TagDecl object that are spelled with "enum."
 ///
-/// Example matches E, but not C, S or U.
+/// Given
 /// \code
 ///   struct S {};
 ///   class C {};
 ///   union U {};
-///   enum E {};
+///   enum E { Ok };
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{tagDecl(isEnum())}
+/// matches \match{count=1$enum E { Ok }},
+/// but does not match \nomatch{count=2$struct S {}},
+/// \nomatch{count=2$class C {}} or \nomatch{count=2$union U {}}.
 AST_MATCHER(TagDecl, isEnum) {
   return Node.isEnum();
 }
@@ -6158,14 +7901,29 @@ AST_MATCHER(TagDecl, isEnum) {
 /// Matches the true branch expression of a conditional operator.
 ///
 /// Example 1 (conditional ternary operator): matches a
+/// Given
 /// \code
-///   condition ? a : b
+///   void foo(bool condition, int a, int b) {
+///     condition ? a : b;
+///   }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher
+/// \matcher{conditionalOperator(hasTrueExpression(expr().bind("true")))}
+/// matches \match{condition ? a : b},
+/// with \matcher{type=sub$expr()} matching \match{sub=true$a}.
 ///
 /// Example 2 (conditional binary operator): matches opaqueValueExpr(condition)
+/// Given
 /// \code
-///   condition ?: b
+///   void foo(bool condition, int a, int b) {
+///     condition ?: b;
+///   }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher \matcher{binaryConditionalOperator(hasTrueExpression(expr()))}
+/// matches \match{condition ?: b},
+/// with \matcher{type=sub$expr()} matching \match{sub=true$conditoin}.
 AST_MATCHER_P(AbstractConditionalOperator, hasTrueExpression,
               internal::Matcher<Expr>, InnerMatcher) {
   const Expr *Expression = Node.getTrueExpr();
@@ -6178,9 +7936,20 @@ AST_MATCHER_P(AbstractConditionalOperator, hasTrueExpression,
 ///
 /// Example matches b
 /// \code
-///   condition ? a : b
-///   condition ?: b
+///   void foo(bool condition, int a, int b) {
+///     condition ? a : b;
+///     condition ?: b;
+///   }
 /// \endcode
+/// \compile_args{-std=c++,c23-or-later}
+/// The matcher
+/// \matcher{conditionalOperator(hasFalseExpression(expr().bind("false")))}
+/// matches \match{condition ? a : b},
+/// with \matcher{type=sub$expr()} matching \match{sub=false$b}.
+/// The matcher
+/// \matcher{binaryConditionalOperator(hasFalseExpression(expr().bind("false")))}
+/// matches \match{condition ?: b},
+/// with \matcher{type=sub$expr()} matching \match{sub=false$b}.
 AST_MATCHER_P(AbstractConditionalOperator, hasFalseExpression,
               internal::Matcher<Expr>, InnerMatcher) {
   const Expr *Expression = Node.getFalseExpr();
@@ -6198,6 +7967,16 @@ AST_MATCHER_P(AbstractConditionalOperator, hasFalseExpression,
 ///   extern int vb;  // Doesn't match, as it doesn't define the variable.
 ///   void fa() {}
 ///   void fb();  // Doesn't match, as it has no body.
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{tagDecl(isDefinition())}
+/// matches \match{type=name$A}
+/// The matcher \matcher{varDecl(isDefinition())}
+/// matches \match{type=name$va}
+/// The matcher \matcher{functionDecl(isDefinition())}
+/// matches \match{type=name$fa}
+///
+/// \code
 ///   @interface X
 ///   - (void)ma; // Doesn't match, interface is declaration.
 ///   @end
@@ -6205,6 +7984,9 @@ AST_MATCHER_P(AbstractConditionalOperator, hasFalseExpression,
 ///   - (void)ma {}
 ///   @end
 /// \endcode
+/// \compile_args{-ObjC}
+/// The matcher \matcher{objcMethodDecl(isDefinition())}
+/// matches \match{- (void)ma {}}
 ///
 /// Usable as: Matcher<TagDecl>, Matcher<VarDecl>, Matcher<FunctionDecl>,
 ///   Matcher<ObjCMethodDecl>
@@ -6225,6 +8007,12 @@ AST_POLYMORPHIC_MATCHER(isDefinition,
 ///   template <typename... Ts> void h(Ts...);
 ///   void i();
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{functionDecl(isVariadic())}
+/// matches \match{void f(...)},
+/// but does not match \nomatch{void g(int)},
+/// \nomatch{template <typename... Ts> void h(Ts...)},
+/// or \nomatch{void i()}.
 AST_MATCHER(FunctionDecl, isVariadic) {
   return Node.isVariadic();
 }
@@ -6236,16 +8024,17 @@ AST_MATCHER(FunctionDecl, isVariadic) {
 /// FIXME: What other kind of declarations would we need to generalize
 /// this to?
 ///
-/// Example matches A() in the last line
-///     (matcher = cxxConstructExpr(hasDeclaration(cxxMethodDecl(
-///         ofClass(hasName("A"))))))
+/// Given
 /// \code
 ///   class A {
 ///    public:
 ///     A();
+///     void foo();
 ///   };
-///   A a = A();
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(ofClass(hasName("A")))}
+/// matches \match{A()} and \match{void foo()}.
 AST_MATCHER_P(CXXMethodDecl, ofClass,
               internal::Matcher<CXXRecordDecl>, InnerMatcher) {
 
@@ -6265,10 +8054,14 @@ AST_MATCHER_P(CXXMethodDecl, ofClass,
 ///   class B : public A { void f(); };
 ///   class C : public B { void f(); };
 /// \endcode
-/// cxxMethodDecl(ofClass(hasName("C")),
-///               forEachOverridden(cxxMethodDecl().bind("b"))).bind("d")
-///   matches once, with "b" binding "A::f" and "d" binding "C::f" (Note
-///   that B::f is not overridden by C::f).
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(ofClass(hasName("C")),
+///               forEachOverridden(cxxMethodDecl().bind("b")))}
+/// matches \match{void f()} of \c C ,
+/// with \matcher{type=sub$cxxMethodDecl()} matching
+/// \match{sub=b$virtual void f()} of \c A ,
+/// but the matcher does not match \nomatch{void f()} of \c B because
+/// it is not overridden by C::f.
 ///
 /// The check can produce multiple matches in case of multiple inheritance, e.g.
 /// \code
@@ -6276,10 +8069,14 @@ AST_MATCHER_P(CXXMethodDecl, ofClass,
 ///   class A2 { virtual void f(); };
 ///   class C : public A1, public A2 { void f(); };
 /// \endcode
-/// cxxMethodDecl(ofClass(hasName("C")),
-///               forEachOverridden(cxxMethodDecl().bind("b"))).bind("d")
-///   matches twice, once with "b" binding "A1::f" and "d" binding "C::f", and
-///   once with "b" binding "A2::f" and "d" binding "C::f".
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(ofClass(hasName("C")),
+///               forEachOverridden(cxxMethodDecl().bind("b")))}
+/// matches \match{void f()} of \c C with the inner
+/// \matcher{type=sub$cxxMethodDecl()} matching \match{sub=b$virtual void f()}
+/// inside of \c A1 , and \match{void f()} of \c C with the inner
+/// \matcher{type=sub$cxxMethodDecl()} matching \match{sub=b$virtual void f()}
+/// inside of \c A2.
 AST_MATCHER_P(CXXMethodDecl, forEachOverridden,
               internal::Matcher<CXXMethodDecl>, InnerMatcher) {
   BoundNodesTreeBuilder Result;
@@ -6300,20 +8097,27 @@ AST_MATCHER_P(CXXMethodDecl, forEachOverridden,
 /// Matches declarations of virtual methods and C++ base specifers that specify
 /// virtual inheritance.
 ///
-/// Example:
+/// Given
 /// \code
 ///   class A {
 ///    public:
 ///     virtual void x(); // matches x
 ///   };
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(isVirtual())}
+/// matches \match{type=name$x}.
 ///
-/// Example:
+/// Given
 /// \code
-///   class Base {};
-///   class DirectlyDerived : virtual Base {}; // matches Base
-///   class IndirectlyDerived : DirectlyDerived, Base {}; // matches Base
+///   struct Base {};
+///   struct DirectlyDerived : virtual Base {}; // matches Base
+///   struct IndirectlyDerived : DirectlyDerived, Base {}; // matches Base
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{cxxRecordDecl(hasDirectBase(cxxBaseSpecifier(isVirtual())))}
+/// matches \match{type=name$DirectlyDerived}.
 ///
 /// Usable as: Matcher<CXXMethodDecl>, Matcher<CXXBaseSpecifier>
 AST_POLYMORPHIC_MATCHER(isVirtual,
@@ -6335,7 +8139,10 @@ AST_POLYMORPHIC_MATCHER(isVirtual,
 ///     void x();
 ///   };
 /// \endcode
-///   matches A::x but not B::x
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(isVirtualAsWritten())}
+/// matches \match{virtual void x()} of \c A,
+/// but does not match \notmatch{void x()} of \c B .
 AST_MATCHER(CXXMethodDecl, isVirtualAsWritten) {
   return Node.isVirtualAsWritten();
 }
@@ -6346,7 +8153,7 @@ AST_MATCHER(CXXConstructorDecl, isInheritingConstructor) {
 
 /// Matches if the given method or class declaration is final.
 ///
-/// Given:
+/// Given
 /// \code
 ///   class A final {};
 ///
@@ -6358,7 +8165,13 @@ AST_MATCHER(CXXConstructorDecl, isInheritingConstructor) {
 ///     void f() final;
 ///   };
 /// \endcode
-/// matches A and C::f, but not B, C, or B::f
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(isFinal())}
+/// matches \match{type=name$A},
+/// but does not match \nomatch{type=name$B} or \nomatch{type=name$C}.
+/// The matcher \matcher{cxxMethodDecl(isFinal())}
+/// matches \match{void f() final} in \c C ,
+/// but does not match \nomatch{virtual void f()} in \c B .
 AST_POLYMORPHIC_MATCHER(isFinal,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(CXXRecordDecl,
                                                         CXXMethodDecl)) {
@@ -6374,7 +8187,9 @@ AST_POLYMORPHIC_MATCHER(isFinal,
 ///     virtual void x() = 0;
 ///   };
 /// \endcode
-///   matches A::x
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(isPure())}
+/// matches \match{virtual void x() = 0}
 AST_MATCHER(CXXMethodDecl, isPure) { return Node.isPureVirtual(); }
 
 /// Matches if the given method declaration is const.
@@ -6386,8 +8201,10 @@ AST_MATCHER(CXXMethodDecl, isPure) { return Node.isPureVirtual(); }
 ///   void bar();
 /// };
 /// \endcode
+/// \compile_args{-std=c++}
 ///
-/// cxxMethodDecl(isConst()) matches A::foo() but not A::bar()
+/// The matcher \matcher{cxxMethodDecl(isConst())}
+/// matches \match{type=name$foo} but not \nomatch{type=name$bar}
 AST_MATCHER(CXXMethodDecl, isConst) {
   return Node.isConst();
 }
@@ -6402,9 +8219,11 @@ AST_MATCHER(CXXMethodDecl, isConst) {
 ///   A &operator=(A &&);
 /// };
 /// \endcode
+/// \compile_args{-std=c++}
 ///
-/// cxxMethodDecl(isCopyAssignmentOperator()) matches the first method but not
-/// the second one.
+/// The matcher \matcher{cxxMethodDecl(isCopyAssignmentOperator())}
+/// matches \match{A &operator=(const A &)}
+/// but does not match \nomatch{A &operator=(A &&)}
 AST_MATCHER(CXXMethodDecl, isCopyAssignmentOperator) {
   return Node.isCopyAssignmentOperator();
 }
@@ -6419,9 +8238,11 @@ AST_MATCHER(CXXMethodDecl, isCopyAssignmentOperator) {
 ///   A &operator=(A &&);
 /// };
 /// \endcode
+/// \compile_args{-std=c++}
 ///
-/// cxxMethodDecl(isMoveAssignmentOperator()) matches the second method but not
-/// the first one.
+/// The matcher \matcher{cxxMethodDecl(isMoveAssignmentOperator())}
+/// matches \match{A &operator=(A &&)}
+/// but does not match \nomatch{A &operator=(const A &)}
 AST_MATCHER(CXXMethodDecl, isMoveAssignmentOperator) {
   return Node.isMoveAssignmentOperator();
 }
@@ -6436,10 +8257,12 @@ AST_MATCHER(CXXMethodDecl, isMoveAssignmentOperator) {
 ///   };
 ///   class B : public A {
 ///    public:
-///     virtual void x();
+///     void x() override;
 ///   };
 /// \endcode
-///   matches B::x
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxMethodDecl(isOverride())}
+///   matches \match{void x() override}
 AST_MATCHER(CXXMethodDecl, isOverride) {
   return Node.size_overridden_methods() > 0 || Node.hasAttr<OverrideAttr>();
 }
@@ -6454,7 +8277,10 @@ AST_MATCHER(CXXMethodDecl, isOverride) {
 ///     S(S &&) = delete; // #3
 ///   };
 /// \endcode
-/// cxxConstructorDecl(isUserProvided()) will match #1, but not #2 or #3.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxConstructorDecl(isUserProvided())}
+/// will match \match{S()}, but not \notmatch{S(const S &) = default} or
+/// \notmatch{S(S &&) = delete}
 AST_MATCHER(CXXMethodDecl, isUserProvided) {
   return Node.isUserProvided();
 }
@@ -6474,15 +8300,26 @@ AST_MATCHER(CXXMethodDecl, isUserProvided) {
 ///   };
 ///   template <class T>
 ///   class Z {
-///     void x() { this->m; }
+///     void x() {
+///       this->m;
+///       this->t;
+///       this->t->m;
+///     }
+///     int m;
+///     T* t;
 ///   };
 /// \endcode
-/// memberExpr(isArrow())
-///   matches this->x, x, y.x, a, this->b
-/// cxxDependentScopeMemberExpr(isArrow())
-///   matches this->m
-/// unresolvedMemberExpr(isArrow())
-///   matches this->f<T>, f<T>
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{memberExpr(isArrow())}
+/// matches \match{this->x}, \match{x}, \match{a},
+/// \match{this->b}, \match{this->m} and two times \match{count=2$this->t},
+/// once for the standalone member expression, and once for the member
+/// expression that later accesses \c m .
+/// Additionally, it does not match \nomatch{this->t->t}.
+/// The matcher \matcher{cxxDependentScopeMemberExpr(isArrow())}
+/// matches \match{this->t->m}, but not \nomatch{this->m} or \nomatch{this->t}.
+/// The matcher \matcher{unresolvedMemberExpr(isArrow())}
+/// matches \match{this->f<T>}, \match{f<T>}
 AST_POLYMORPHIC_MATCHER(
     isArrow, AST_POLYMORPHIC_SUPPORTED_TYPES(MemberExpr, UnresolvedMemberExpr,
                                              CXXDependentScopeMemberExpr)) {
@@ -6497,8 +8334,8 @@ AST_POLYMORPHIC_MATCHER(
 ///   void b(long);
 ///   void c(double);
 /// \endcode
-/// functionDecl(hasAnyParameter(hasType(isInteger())))
-/// matches "a(int)", "b(long)", but not "c(double)".
+/// The matcher \matcher{functionDecl(hasAnyParameter(hasType(isInteger())))}
+/// \match{type=name$a}, \match{type=name$b}, but not \nomatch{type=name$c}.
 AST_MATCHER(QualType, isInteger) {
     return Node->isIntegerType();
 }
@@ -6511,8 +8348,10 @@ AST_MATCHER(QualType, isInteger) {
 ///   void b(unsigned long);
 ///   void c(double);
 /// \endcode
-/// functionDecl(hasAnyParameter(hasType(isUnsignedInteger())))
-/// matches "b(unsigned long)", but not "a(int)" and "c(double)".
+/// The matcher
+/// \matcher{functionDecl(hasAnyParameter(hasType(isUnsignedInteger())))}
+/// matches \match{type=name$b},
+/// but does not match \nomatch{type=name$a} and \nomatch{type=name$c}.
 AST_MATCHER(QualType, isUnsignedInteger) {
     return Node->isUnsignedIntegerType();
 }
@@ -6525,8 +8364,10 @@ AST_MATCHER(QualType, isUnsignedInteger) {
 ///   void b(unsigned long);
 ///   void c(double);
 /// \endcode
-/// functionDecl(hasAnyParameter(hasType(isSignedInteger())))
-/// matches "a(int)", but not "b(unsigned long)" and "c(double)".
+/// The matcher
+/// \matcher{functionDecl(hasAnyParameter(hasType(isSignedInteger())))} matches
+/// \match{type=name$a}, but not \notmatch{type=name$b} and not
+/// \notmatch{type=name$c}.
 AST_MATCHER(QualType, isSignedInteger) {
     return Node->isSignedIntegerType();
 }
@@ -6539,8 +8380,11 @@ AST_MATCHER(QualType, isSignedInteger) {
 ///   void b(wchar_t);
 ///   void c(double);
 /// \endcode
-/// functionDecl(hasAnyParameter(hasType(isAnyCharacter())))
-/// matches "a(char)", "b(wchar_t)", but not "c(double)".
+/// \compile_args{-std=c++}
+///
+/// The matcher
+/// \matcher{functionDecl(hasAnyParameter(hasType(isAnyCharacter())))}
+/// \match{type=name$a}, \match{type=name$b}, but not \notmatch{type=name$c}.
 AST_MATCHER(QualType, isAnyCharacter) {
     return Node->isAnyCharacterType();
 }
@@ -6559,8 +8403,9 @@ AST_MATCHER(QualType, isAnyCharacter) {
 ///
 ///   int j;
 /// \endcode
-/// varDecl(hasType(isAnyPointer()))
-///   matches "int *i" and "Foo *f", but not "int j".
+/// \compile_args{-ObjC}
+/// The matcher \matcher{varDecl(hasType(isAnyPointer()))}
+/// \match{int *i} and \match{Foo *f}, but not \nomatch{int j}.
 AST_MATCHER(QualType, isAnyPointer) {
   return Node->isAnyPointerType();
 }
@@ -6576,9 +8421,11 @@ AST_MATCHER(QualType, isAnyPointer) {
 ///   void d(const int*);
 ///   void e(int const) {};
 /// \endcode
-/// functionDecl(hasAnyParameter(hasType(isConstQualified())))
-///   matches "void b(int const)", "void c(const int)" and
-///   "void e(int const) {}". It does not match d as there
+/// The matcher
+/// \matcher{functionDecl(hasAnyParameter(hasType(isConstQualified())))}
+///   matches \match{type=name$b}, \match{type=name$c} and
+///   \match{type=name$e}.
+///   It does not match \notmatch{type=name$d} as there
 ///   is no top-level const on the parameter type "const int *".
 AST_MATCHER(QualType, isConstQualified) {
   return Node.isConstQualified();
@@ -6595,9 +8442,11 @@ AST_MATCHER(QualType, isConstQualified) {
 ///   void d(volatile int*);
 ///   void e(int volatile) {};
 /// \endcode
-/// functionDecl(hasAnyParameter(hasType(isVolatileQualified())))
-///   matches "void b(int volatile)", "void c(volatile int)" and
-///   "void e(int volatile) {}". It does not match d as there
+/// The matcher
+/// \matcher{functionDecl(hasAnyParameter(hasType(isVolatileQualified())))}
+///   matches \match{type=name$b}, \match{type=name$c} and
+///   \match{type=name$e}.
+///   It does not match \notmatch{type=name$d} as there
 ///   is no top-level volatile on the parameter type "volatile int *".
 AST_MATCHER(QualType, isVolatileQualified) {
   return Node.isVolatileQualified();
@@ -6609,13 +8458,16 @@ AST_MATCHER(QualType, isVolatileQualified) {
 /// Given
 /// \code
 ///   typedef const int const_int;
-///   const_int i;
-///   int *const j;
+///   const_int i = 0;
+///   int *const j = nullptr;
 ///   int *volatile k;
 ///   int m;
 /// \endcode
-/// \c varDecl(hasType(hasLocalQualifiers())) matches only \c j and \c k.
-/// \c i is const-qualified but the qualifier is not local.
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{varDecl(hasType(hasLocalQualifiers()))} matches only
+/// \match{type=name$j} and \match{type=name$k}. \notmatch{type=name$i} is
+/// const-qualified but the qualifier is not local.
 AST_MATCHER(QualType, hasLocalQualifiers) {
   return Node.hasLocalQualifiers();
 }
@@ -6625,13 +8477,15 @@ AST_MATCHER(QualType, hasLocalQualifiers) {
 ///
 /// Given
 /// \code
-///   struct { int first, second; } first, second;
-///   int i(second.first);
-///   int j(first.second);
+///   struct { int first = 0, second = 1; } first, second;
+///   int i = second.first;
+///   int j = first.second;
 /// \endcode
-/// memberExpr(member(hasName("first")))
-///   matches second.first
-///   but not first.second (because the member name there is "second").
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{memberExpr(member(hasName("first")))}
+/// matches \match{second.first}
+/// but not \notmatch{first.second}.
 AST_MATCHER_P(MemberExpr, member,
               internal::Matcher<ValueDecl>, InnerMatcher) {
   return InnerMatcher.matches(*Node.getMemberDecl(), Finder, Builder);
@@ -6648,11 +8502,14 @@ AST_MATCHER_P(MemberExpr, member,
 ///     int f(X x) { x.m; return m; }
 ///   };
 /// \endcode
-/// memberExpr(hasObjectExpression(hasType(cxxRecordDecl(hasName("X")))))
-///   matches `x.m`, but not `m`; however,
-/// memberExpr(hasObjectExpression(hasType(pointsTo(
-//      cxxRecordDecl(hasName("X"))))))
-///   matches `m` (aka. `this->m`), but not `x.m`.
+/// \compile_args{-std=c++}
+///
+/// The matcher
+/// \matcher{memberExpr(hasObjectExpression(hasType(cxxRecordDecl(hasName("X")))))}
+/// matches \match{x.m}, but not \nomatch{m}; however,
+/// The matcher \matcher{memberExpr(hasObjectExpression(hasType(pointsTo(
+/// cxxRecordDecl(hasName("X"))))))}
+/// matches \match{m} (aka. this->m), but not \nomatch{x.m}.
 AST_POLYMORPHIC_MATCHER_P(
     hasObjectExpression,
     AST_POLYMORPHIC_SUPPORTED_TYPES(MemberExpr, UnresolvedMemberExpr,
@@ -6674,8 +8531,9 @@ AST_POLYMORPHIC_MATCHER_P(
 ///   namespace X { void b(); }
 ///   using X::b;
 /// \endcode
-/// usingDecl(hasAnyUsingShadowDecl(hasName("b"))))
-///   matches \code using X::b \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{usingDecl(hasAnyUsingShadowDecl(hasName("b")))}
+///   matches \match{using X::b}
 AST_MATCHER_P(BaseUsingDecl, hasAnyUsingShadowDecl,
               internal::Matcher<UsingShadowDecl>, InnerMatcher) {
   return matchesFirstInPointerRange(InnerMatcher, Node.shadow_begin(),
@@ -6692,9 +8550,11 @@ AST_MATCHER_P(BaseUsingDecl, hasAnyUsingShadowDecl,
 ///   using X::a;
 ///   using X::b;
 /// \endcode
-/// usingDecl(hasAnyUsingShadowDecl(hasTargetDecl(functionDecl())))
-///   matches \code using X::b \endcode
-///   but not \code using X::a \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher
+/// \matcher{usingDecl(hasAnyUsingShadowDecl(hasTargetDecl(functionDecl())))}
+///   matches \match{using X::b}
+///   but not \notmatch{using X::a}
 AST_MATCHER_P(UsingShadowDecl, hasTargetDecl,
               internal::Matcher<NamedDecl>, InnerMatcher) {
   return InnerMatcher.matches(*Node.getTargetDecl(), Finder, Builder);
@@ -6705,26 +8565,44 @@ AST_MATCHER_P(UsingShadowDecl, hasTargetDecl,
 ///
 /// Given
 /// \code
-///   template <typename T> class X {}; class A {}; X<A> x;
+///   template <typename T> class X {};
+///   class A {};
+///   X<A> x;
 /// \endcode
-/// or
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{cxxRecordDecl(hasName("::X"),
+/// isTemplateInstantiation())}
+/// matches \match{type=typestr$class X<class A>}.
 /// \code
-///   template <typename T> class X {}; class A {}; template class X<A>;
+///   template <typename T> class X {};
+///   class A {};
+///   template class X<A>;
 /// \endcode
-/// or
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{cxxRecordDecl(hasName("::X"),
+/// isTemplateInstantiation())}
+/// matches \match{template class X<A>}
 /// \code
-///   template <typename T> class X {}; class A {}; extern template class X<A>;
+///   template <typename T> class X {};
+///   class A {};
+///   extern template class X<A>;
 /// \endcode
-/// cxxRecordDecl(hasName("::X"), isTemplateInstantiation())
-///   matches the template instantiation of X<A>.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{cxxRecordDecl(hasName("::X"),
+/// isTemplateInstantiation())}
+/// matches \match{extern template class X<A>}
 ///
 /// But given
 /// \code
-///   template <typename T>  class X {}; class A {};
-///   template <> class X<A> {}; X<A> x;
+///   template <typename T>  class X {};
+///   class A {};
+///   template <> class X<A> {};
+///   X<A> x;
 /// \endcode
-/// cxxRecordDecl(hasName("::X"), isTemplateInstantiation())
-///   does not match, as X<A> is an explicit template specialization.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{cxxRecordDecl(hasName("::X"),
+/// isTemplateInstantiation())}
+///   \nomatch{} does not match, as X<A> is an explicit template specialization.
 ///
 /// Usable as: Matcher<FunctionDecl>, Matcher<VarDecl>, Matcher<CXXRecordDecl>
 AST_POLYMORPHIC_MATCHER(isTemplateInstantiation,
@@ -6743,11 +8621,15 @@ AST_POLYMORPHIC_MATCHER(isTemplateInstantiation,
 /// Given
 /// \code
 ///   template<typename T> void A(T t) { T i; }
-///   A(0);
-///   A(0U);
+///   void foo() {
+///     A(0);
+///     A(0U);
+///   }
 /// \endcode
-/// functionDecl(isInstantiated())
-///   matches 'A(int) {...};' and 'A(unsigned) {...}'.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{functionDecl(isInstantiated())}
+/// matches the two instantiations of \match{count=2$void A(T t) { T i; }} that
+/// are generated for \c int , and for \c{unsigned int}.
 AST_MATCHER_FUNCTION(internal::Matcher<Decl>, isInstantiated) {
   auto IsInstantiation = decl(anyOf(cxxRecordDecl(isTemplateInstantiation()),
                                     functionDecl(isTemplateInstantiation())));
@@ -6759,15 +8641,19 @@ AST_MATCHER_FUNCTION(internal::Matcher<Decl>, isInstantiated) {
 /// Given
 /// \code
 ///   int j;
-///   template<typename T> void A(T t) { T i; j += 42;}
-///   A(0);
-///   A(0U);
-/// \endcode
-/// declStmt(isInTemplateInstantiation())
-///   matches 'int i;' and 'unsigned i'.
-/// unless(stmt(isInTemplateInstantiation()))
-///   will NOT match j += 42; as it's shared between the template definition and
-///   instantiation.
+///   template<typename T> void A(T t) { T i; }
+///   void foo() {
+///     A(0);
+///     A(0U);
+///   }
+/// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{declStmt(isInTemplateInstantiation())}
+/// matches \match{count=2$T i;} twice, once for \c int and once for
+/// \c{unsigned int}.
+/// The matcher \matcher{declStmt(unless(isInTemplateInstantiation()))} will
+/// match \match{T i;} once inside the template definition, but not for any of
+/// the instantiated bodies.
 AST_MATCHER_FUNCTION(internal::Matcher<Stmt>, isInTemplateInstantiation) {
   return stmt(
       hasAncestor(decl(anyOf(cxxRecordDecl(isTemplateInstantiation()),
@@ -6782,8 +8668,9 @@ AST_MATCHER_FUNCTION(internal::Matcher<Stmt>, isInTemplateInstantiation) {
 ///   template<typename T> void A(T t) { }
 ///   template<> void A(int N) { }
 /// \endcode
-/// functionDecl(isExplicitTemplateSpecialization())
-///   matches the specialization A<int>().
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{functionDecl(isExplicitTemplateSpecialization())}
+///   matches the specialization \match{template<> void A(int N) { }}.
 ///
 /// Usable as: Matcher<FunctionDecl>, Matcher<VarDecl>, Matcher<CXXRecordDecl>
 AST_POLYMORPHIC_MATCHER(isExplicitTemplateSpecialization,
@@ -6794,6 +8681,13 @@ AST_POLYMORPHIC_MATCHER(isExplicitTemplateSpecialization,
 
 /// Matches \c TypeLocs for which the given inner
 /// QualType-matcher matches.
+///
+/// \code
+///   int a = 10;
+/// \endcode
+///
+/// The matcher \matcher{typeLoc(loc(qualType(isInteger())))}
+/// matches the \match{int} of \c a .
 AST_MATCHER_FUNCTION_P_OVERLOAD(internal::BindableMatcher<TypeLoc>, loc,
                                 internal::Matcher<QualType>, InnerMatcher, 0) {
   return internal::BindableMatcher<TypeLoc>(
@@ -6806,8 +8700,11 @@ AST_MATCHER_FUNCTION_P_OVERLOAD(internal::BindableMatcher<TypeLoc>, loc,
 /// \code
 ///   const int x = 0;
 /// \endcode
-/// qualifiedTypeLoc()
-///   matches `const int`.
+///
+/// The matcher \matcher{qualifiedTypeLoc()}
+/// matches the type of the variable declaration \c x . However, the
+/// current implementation of \c QualifiedTypeLoc does not store the source
+/// locations for the qualifiers of the type \match{int}.
 extern const internal::VariadicDynCastAllOfMatcher<TypeLoc, QualifiedTypeLoc>
     qualifiedTypeLoc;
 
@@ -6816,11 +8713,14 @@ extern const internal::VariadicDynCastAllOfMatcher<TypeLoc, QualifiedTypeLoc>
 ///
 /// Given
 /// \code
-///   int* const x;
-///   const int y;
+///   int* const x = nullptr;
+///   const int y = 0;
 /// \endcode
-/// qualifiedTypeLoc(hasUnqualifiedLoc(pointerTypeLoc()))
-///   matches the `TypeLoc` of the variable declaration of `x`, but not `y`.
+/// \compile_args{-std=c++11-or-later,c23-or-later}
+///
+/// The matcher \matcher{qualifiedTypeLoc(hasUnqualifiedLoc(pointerTypeLoc()))}
+/// matches the type \match{int*} of the variable declaration \c{x}, but
+/// not \c{y}.
 AST_MATCHER_P(QualifiedTypeLoc, hasUnqualifiedLoc, internal::Matcher<TypeLoc>,
               InnerMatcher) {
   return InnerMatcher.matches(Node.getUnqualifiedLoc(), Finder, Builder);
@@ -6833,8 +8733,9 @@ AST_MATCHER_P(QualifiedTypeLoc, hasUnqualifiedLoc, internal::Matcher<TypeLoc>,
 ///   int f() { return 5; }
 ///   void g() {}
 /// \endcode
-/// functionDecl(hasReturnTypeLoc(loc(asString("int"))))
-///   matches the declaration of `f`, but not `g`.
+/// The matcher \matcher{functionDecl(hasReturnTypeLoc(loc(asString("int"))))}
+///   matches the declaration of \match{type=name$f}, but not
+///   \notmatch{type=name$g}.
 AST_MATCHER_P(FunctionDecl, hasReturnTypeLoc, internal::Matcher<TypeLoc>,
               ReturnMatcher) {
   auto Loc = Node.getFunctionTypeLoc();
@@ -6847,8 +8748,8 @@ AST_MATCHER_P(FunctionDecl, hasReturnTypeLoc, internal::Matcher<TypeLoc>,
 /// \code
 ///   int* x;
 /// \endcode
-/// pointerTypeLoc()
-///   matches `int*`.
+/// The matcher \matcher{pointerTypeLoc()}
+///   matches \match{int*}.
 extern const internal::VariadicDynCastAllOfMatcher<TypeLoc, PointerTypeLoc>
     pointerTypeLoc;
 
@@ -6859,8 +8760,8 @@ extern const internal::VariadicDynCastAllOfMatcher<TypeLoc, PointerTypeLoc>
 /// \code
 ///   int* x;
 /// \endcode
-/// pointerTypeLoc(hasPointeeLoc(loc(asString("int"))))
-///   matches `int*`.
+/// The matcher \matcher{pointerTypeLoc(hasPointeeLoc(loc(asString("int"))))}
+///   matches \match{int*}.
 AST_MATCHER_P(PointerTypeLoc, hasPointeeLoc, internal::Matcher<TypeLoc>,
               PointeeMatcher) {
   return PointeeMatcher.matches(Node.getPointeeLoc(), Finder, Builder);
@@ -6874,8 +8775,10 @@ AST_MATCHER_P(PointerTypeLoc, hasPointeeLoc, internal::Matcher<TypeLoc>,
 ///   int& l = x;
 ///   int&& r = 3;
 /// \endcode
-/// referenceTypeLoc()
-///   matches `int&` and `int&&`.
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{referenceTypeLoc()}
+///   matches \match{int&} and \match{int&&}.
 extern const internal::VariadicDynCastAllOfMatcher<TypeLoc, ReferenceTypeLoc>
     referenceTypeLoc;
 
@@ -6887,8 +8790,10 @@ extern const internal::VariadicDynCastAllOfMatcher<TypeLoc, ReferenceTypeLoc>
 ///   int x = 3;
 ///   int& xx = x;
 /// \endcode
-/// referenceTypeLoc(hasReferentLoc(loc(asString("int"))))
-///   matches `int&`.
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{referenceTypeLoc(hasReferentLoc(loc(asString("int"))))}
+///   matches \match{int&}.
 AST_MATCHER_P(ReferenceTypeLoc, hasReferentLoc, internal::Matcher<TypeLoc>,
               ReferentMatcher) {
   return ReferentMatcher.matches(Node.getPointeeLoc(), Finder, Builder);
@@ -6901,8 +8806,11 @@ AST_MATCHER_P(ReferenceTypeLoc, hasReferentLoc, internal::Matcher<TypeLoc>,
 ///   template <typename T> class C {};
 ///   C<char> var;
 /// \endcode
-/// varDecl(hasTypeLoc(templateSpecializationTypeLoc(typeLoc())))
-///   matches `C<char> var`.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+/// templateSpecializationTypeLoc(typeLoc())))))}
+/// matches \match{C<char> var}.
 extern const internal::VariadicDynCastAllOfMatcher<
     TypeLoc, TemplateSpecializationTypeLoc>
     templateSpecializationTypeLoc;
@@ -6917,9 +8825,11 @@ extern const internal::VariadicDynCastAllOfMatcher<
 ///   template<typename T> class A {};
 ///   A<int> a;
 /// \endcode
-/// varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
-///   hasTypeLoc(loc(asString("int")))))))
-///   matches `A<int> a`.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+/// templateSpecializationTypeLoc(hasAnyTemplateArgumentLoc(
+/// hasTypeLoc(loc(asString("int")))))))))} matches \match{A<int> a}.
 AST_POLYMORPHIC_MATCHER_P(
     hasAnyTemplateArgumentLoc,
     AST_POLYMORPHIC_SUPPORTED_TYPES(ClassTemplateSpecializationDecl,
@@ -6942,9 +8852,12 @@ AST_POLYMORPHIC_MATCHER_P(
 ///   A<double, int> b;
 ///   A<int, double> c;
 /// \endcode
-/// varDecl(hasTypeLoc(templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
-///   hasTypeLoc(loc(asString("double")))))))
-///   matches `A<double, int> b`, but not `A<int, double> c`.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{varDecl(hasTypeLoc(elaboratedTypeLoc(hasNamedTypeLoc(
+/// templateSpecializationTypeLoc(hasTemplateArgumentLoc(0,
+/// hasTypeLoc(loc(asString("double")))))))))}
+/// matches \match{A<double, int> b}, but not \notmatch{A<int, double> c}.
 AST_POLYMORPHIC_MATCHER_P2(
     hasTemplateArgumentLoc,
     AST_POLYMORPHIC_SUPPORTED_TYPES(ClassTemplateSpecializationDecl,
@@ -6963,8 +8876,8 @@ AST_POLYMORPHIC_MATCHER_P2(
 ///   struct s {};
 ///   struct s ss;
 /// \endcode
-/// elaboratedTypeLoc()
-///   matches the `TypeLoc` of the variable declaration of `ss`.
+/// The matcher \matcher{elaboratedTypeLoc()}
+/// matches the type \match{struct s} of \c ss.
 extern const internal::VariadicDynCastAllOfMatcher<TypeLoc, ElaboratedTypeLoc>
     elaboratedTypeLoc;
 
@@ -6980,8 +8893,10 @@ extern const internal::VariadicDynCastAllOfMatcher<TypeLoc, ElaboratedTypeLoc>
 ///   class D {};
 ///   class D d;
 /// \endcode
-/// elaboratedTypeLoc(hasNamedTypeLoc(templateSpecializationTypeLoc()));
-///   matches the `TypeLoc` of the variable declaration of `c`, but not `d`.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{elaboratedTypeLoc(hasNamedTypeLoc(templateSpecializationTypeLoc()))}
+///   matches \match{class C<int>}, but not \notmatch{ckass D}
 AST_MATCHER_P(ElaboratedTypeLoc, hasNamedTypeLoc, internal::Matcher<TypeLoc>,
               InnerMatcher) {
   return InnerMatcher.matches(Node.getNamedTypeLoc(), Finder, Builder);
@@ -6993,8 +8908,9 @@ AST_MATCHER_P(ElaboratedTypeLoc, hasNamedTypeLoc, internal::Matcher<TypeLoc>,
 /// \code
 ///  struct S { bool func(); };
 /// \endcode
-/// functionDecl(returns(booleanType()))
-///   matches "bool func();"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{functionDecl(returns(booleanType()))}
+/// \match{type=name$func}
 AST_MATCHER(Type, booleanType) {
   return Node.isBooleanType();
 }
@@ -7005,8 +8921,10 @@ AST_MATCHER(Type, booleanType) {
 /// \code
 ///  struct S { void func(); };
 /// \endcode
-/// functionDecl(returns(voidType()))
-///   matches "void func();"
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{functionDecl(returns(voidType()))}
+/// \match{type=name$func}
 AST_MATCHER(Type, voidType) {
   return Node.isVoidType();
 }
@@ -7018,14 +8936,13 @@ using AstTypeMatcher = internal::VariadicDynCastAllOfMatcher<Type, NodeType>;
 ///
 /// Given
 /// \code
-///   struct A {};
-///   A a;
+///   enum E { Ok };
+///   enum E e;
 ///   int b;
 ///   float c;
-///   bool d;
 /// \endcode
-/// builtinType()
-///   matches "int b", "float c" and "bool d"
+/// The matcher \matcher{varDecl(hasType(builtinType()))}
+/// matches \match{int b} and \match{float c}.
 extern const AstTypeMatcher<BuiltinType> builtinType;
 
 /// Matches all kinds of arrays.
@@ -7036,8 +8953,9 @@ extern const AstTypeMatcher<BuiltinType> builtinType;
 ///   int b[4];
 ///   void f() { int c[a[0]]; }
 /// \endcode
-/// arrayType()
-///   matches "int a[]", "int b[4]" and "int c[a[0]]";
+/// The matcher \matcher{arrayType()}
+/// \match{type=typestr$int[4]}, \match{type=typestr$int[a[0]]} and
+/// \match{type=typestr$int[]};
 extern const AstTypeMatcher<ArrayType> arrayType;
 
 /// Matches C99 complex types.
@@ -7046,8 +8964,8 @@ extern const AstTypeMatcher<ArrayType> arrayType;
 /// \code
 ///   _Complex float f;
 /// \endcode
-/// complexType()
-///   matches "_Complex float f"
+/// The matcher \matcher{complexType()}
+/// \match{type=typestr$_Complex float}
 extern const AstTypeMatcher<ComplexType> complexType;
 
 /// Matches any real floating-point type (float, double, long double).
@@ -7057,8 +8975,9 @@ extern const AstTypeMatcher<ComplexType> complexType;
 ///   int i;
 ///   float f;
 /// \endcode
-/// realFloatingPointType()
-///   matches "float f" but not "int i"
+/// The matcher \matcher{type(realFloatingPointType())}
+/// matches \match{type=typestr$float}
+/// but does not match \nomatch{type=typestr$int}.
 AST_MATCHER(Type, realFloatingPointType) {
   return Node.isRealFloatingType();
 }
@@ -7072,8 +8991,10 @@ AST_MATCHER(Type, realFloatingPointType) {
 ///   A a[7];
 ///   int b[7];
 /// \endcode
-/// arrayType(hasElementType(builtinType()))
-///   matches "int b[7]"
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{arrayType(hasElementType(builtinType()))}
+/// \match{type=typestr$int[7]}
 ///
 /// Usable as: Matcher<ArrayType>, Matcher<ComplexType>
 AST_TYPELOC_TRAVERSE_MATCHER_DECL(hasElementType, getElement,
@@ -7084,14 +9005,14 @@ AST_TYPELOC_TRAVERSE_MATCHER_DECL(hasElementType, getElement,
 ///
 /// Given
 /// \code
-///   void() {
+///   void foo() {
 ///     int a[2];
 ///     int b[] = { 2, 3 };
 ///     int c[b[0]];
 ///   }
 /// \endcode
-/// constantArrayType()
-///   matches "int a[2]"
+/// The matcher \matcher{constantArrayType()}
+/// \match{type=typestr$int[2]}
 extern const AstTypeMatcher<ConstantArrayType> constantArrayType;
 
 /// Matches nodes that have the specified size.
@@ -7105,10 +9026,11 @@ extern const AstTypeMatcher<ConstantArrayType> constantArrayType;
 ///   wchar_t *ws = L"abcd";
 ///   char *w = "a";
 /// \endcode
-/// constantArrayType(hasSize(42))
-///   matches "int a[42]" and "int b[2 * 21]"
-/// stringLiteral(hasSize(4))
-///   matches "abcd", L"abcd"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{constantArrayType(hasSize(42))}
+/// matches \match{type=typestr;count=2$int[42]} twice.
+/// The matcher \matcher{stringLiteral(hasSize(4))}
+/// matches \match{"abcd"} and \match{L"abcd"}.
 AST_POLYMORPHIC_MATCHER_P(hasSize,
                           AST_POLYMORPHIC_SUPPORTED_TYPES(ConstantArrayType,
                                                           StringLiteral),
@@ -7125,8 +9047,9 @@ AST_POLYMORPHIC_MATCHER_P(hasSize,
 ///     T data[Size];
 ///   };
 /// \endcode
-/// dependentSizedArrayType()
-///   matches "T data[Size]"
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{dependentSizedArrayType()}
+/// \match{type=typestr$T[Size]}
 extern const AstTypeMatcher<DependentSizedArrayType> dependentSizedArrayType;
 
 /// Matches C++ extended vector type where either the type or size is
@@ -7139,8 +9062,9 @@ extern const AstTypeMatcher<DependentSizedArrayType> dependentSizedArrayType;
 ///     typedef T __attribute__((ext_vector_type(Size))) type;
 ///   };
 /// \endcode
-/// dependentSizedExtVectorType()
-///   matches "T __attribute__((ext_vector_type(Size)))"
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{dependentSizedExtVectorType()}
+/// \match{type=typestr$T __attribute__((ext_vector_type(Size)))}
 extern const AstTypeMatcher<DependentSizedExtVectorType>
     dependentSizedExtVectorType;
 
@@ -7152,8 +9076,8 @@ extern const AstTypeMatcher<DependentSizedExtVectorType>
 ///   int b[42];
 ///   void f(int c[]) { int d[a[0]]; };
 /// \endcode
-/// incompleteArrayType()
-///   matches "int a[]" and "int c[]"
+/// The matcher \matcher{incompleteArrayType()}
+/// \match{type=typestr$int[]} and \match{type=typestr$int[]}
 extern const AstTypeMatcher<IncompleteArrayType> incompleteArrayType;
 
 /// Matches C arrays with a specified size that is not an
@@ -7162,13 +9086,13 @@ extern const AstTypeMatcher<IncompleteArrayType> incompleteArrayType;
 /// Given
 /// \code
 ///   void f() {
-///     int a[] = { 2, 3 }
+///     int a[] = { 2, 3 };
 ///     int b[42];
 ///     int c[a[0]];
 ///   }
 /// \endcode
-/// variableArrayType()
-///   matches "int c[a[0]]"
+/// The matcher \matcher{variableArrayType()}
+/// \match{type=typestr$int[a[0]]}
 extern const AstTypeMatcher<VariableArrayType> variableArrayType;
 
 /// Matches \c VariableArrayType nodes that have a specific size
@@ -7180,9 +9104,10 @@ extern const AstTypeMatcher<VariableArrayType> variableArrayType;
 ///     int a[b];
 ///   }
 /// \endcode
-/// variableArrayType(hasSizeExpr(ignoringImpCasts(declRefExpr(to(
-///   varDecl(hasName("b")))))))
-///   matches "int a[b]"
+/// The matcher
+/// \matcher{variableArrayType(hasSizeExpr(ignoringImpCasts(declRefExpr(to(
+///   varDecl(hasName("b")))))))}
+/// matches \match{type=typestr$int[b]}
 AST_MATCHER_P(VariableArrayType, hasSizeExpr,
               internal::Matcher<Expr>, InnerMatcher) {
   return InnerMatcher.matches(*Node.getSizeExpr(), Finder, Builder);
@@ -7194,8 +9119,8 @@ AST_MATCHER_P(VariableArrayType, hasSizeExpr,
 /// \code
 ///   _Atomic(int) i;
 /// \endcode
-/// atomicType()
-///   matches "_Atomic(int) i"
+/// The matcher \matcher{atomicType()}
+/// \match{type=typestr$_Atomic(int)}
 extern const AstTypeMatcher<AtomicType> atomicType;
 
 /// Matches atomic types with a specific value type.
@@ -7205,8 +9130,8 @@ extern const AstTypeMatcher<AtomicType> atomicType;
 ///   _Atomic(int) i;
 ///   _Atomic(float) f;
 /// \endcode
-/// atomicType(hasValueType(isInteger()))
-///  matches "_Atomic(int) i"
+/// The matcher \matcher{atomicType(hasValueType(isInteger()))}
+/// \match{type=typestr$_Atomic(int)}.
 ///
 /// Usable as: Matcher<AtomicType>
 AST_TYPELOC_TRAVERSE_MATCHER_DECL(hasValueType, getValue,
@@ -7214,26 +9139,32 @@ AST_TYPELOC_TRAVERSE_MATCHER_DECL(hasValueType, getValue,
 
 /// Matches types nodes representing C++11 auto types.
 ///
-/// Given:
+/// Given
 /// \code
-///   auto n = 4;
-///   int v[] = { 2, 3 }
-///   for (auto i : v) { }
+///   void foo() {
+///     auto n = 4;
+///     int v[] = { 2, 3 };
+///     for (auto i : v) { };
+///   }
 /// \endcode
-/// autoType()
-///   matches "auto n" and "auto i"
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{autoType()}
+/// matches the \match{type=typestr;count=5$auto} of \c n and \c i ,
+/// as well as the auto types for the implicitly generated code of the range-for
+/// loop (for the range, the begin iterator and the end iterator).
 extern const AstTypeMatcher<AutoType> autoType;
 
 /// Matches types nodes representing C++11 decltype(<expr>) types.
 ///
-/// Given:
+/// Given
 /// \code
 ///   short i = 1;
 ///   int j = 42;
 ///   decltype(i + j) result = i + j;
 /// \endcode
-/// decltypeType()
-///   matches "decltype(i + j)"
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{decltypeType()}
+/// \match{type=typestr$decltype(i + j)}
 extern const AstTypeMatcher<DecltypeType> decltypeType;
 
 /// Matches \c AutoType nodes where the deduced type is a specific type.
@@ -7246,8 +9177,10 @@ extern const AstTypeMatcher<DecltypeType> decltypeType;
 ///   auto a = 1;
 ///   auto b = 2.0;
 /// \endcode
-/// autoType(hasDeducedType(isInteger()))
-///   matches "auto a"
+/// \compile_args{-std=c++11-or-later}
+/// The matcher
+/// \matcher{varDecl(hasType(autoType(hasDeducedType(isInteger()))))}
+/// matches \match{auto a = 1}, but does not match \nomatch{auto b = 2.0}.
 ///
 /// Usable as: Matcher<AutoType>
 AST_TYPE_TRAVERSE_MATCHER(hasDeducedType, getDeducedType,
@@ -7260,8 +9193,11 @@ AST_TYPE_TRAVERSE_MATCHER(hasDeducedType, getDeducedType,
 ///   decltype(1) a = 1;
 ///   decltype(2.0) b = 2.0;
 /// \endcode
-/// decltypeType(hasUnderlyingType(isInteger()))
-///   matches the type of "a"
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{decltypeType(hasUnderlyingType(isInteger()))}
+/// matches the type \match{type=typestr$decltype(1)} of the variable
+/// declaration of \c a .
 ///
 /// Usable as: Matcher<DecltypeType>, Matcher<UsingType>
 AST_TYPE_TRAVERSE_MATCHER(hasUnderlyingType, getUnderlyingType,
@@ -7275,8 +9211,12 @@ AST_TYPE_TRAVERSE_MATCHER(hasUnderlyingType, getUnderlyingType,
 ///   int (*f)(int);
 ///   void g();
 /// \endcode
-/// functionType()
-///   matches "int (*f)(int)" and the type of "g".
+/// The matcher \matcher{functionType()}
+/// \match{type=typestr$int (int)} and the type of
+/// \match{std=c++,c23-or-later;type=typestr$void (void)} in C++ and in C23 and
+/// later. Before C23, the function type for \c f will be matched the same way,
+/// but the function type for \c g will match
+/// \match{std=c17-or-earlier;type=typestr$void ()}.
 extern const AstTypeMatcher<FunctionType> functionType;
 
 /// Matches \c FunctionProtoType nodes.
@@ -7286,9 +9226,11 @@ extern const AstTypeMatcher<FunctionType> functionType;
 ///   int (*f)(int);
 ///   void g();
 /// \endcode
-/// functionProtoType()
-///   matches "int (*f)(int)" and the type of "g" in C++ mode.
-///   In C mode, "g" is not matched because it does not contain a prototype.
+/// The matcher \matcher{functionProtoType()}
+/// matches the type \match{type=typestr$int (int)} of 'f' and the type
+/// \match{std=c++,c23-or-later;type=typestr$void (void)} of 'g' in C++ mode.
+/// In C, the type \nomatch{std=c;type=typestr$void ()} of 'g' is not
+/// matched because it does not contain a prototype.
 extern const AstTypeMatcher<FunctionProtoType> functionProtoType;
 
 /// Matches \c ParenType nodes.
@@ -7299,8 +9241,9 @@ extern const AstTypeMatcher<FunctionProtoType> functionProtoType;
 ///   int *array_of_ptrs[4];
 /// \endcode
 ///
-/// \c varDecl(hasType(pointsTo(parenType()))) matches \c ptr_to_array but not
-/// \c array_of_ptrs.
+/// The matcher \matcher{varDecl(hasType(pointsTo(parenType())))}
+///   matches \match{type=name$ptr_to_array} but not
+///   \nomatch{type=name$array_of_ptrs}.
 extern const AstTypeMatcher<ParenType> parenType;
 
 /// Matches \c ParenType nodes where the inner type is a specific type.
@@ -7311,8 +9254,10 @@ extern const AstTypeMatcher<ParenType> parenType;
 ///   int (*ptr_to_func)(int);
 /// \endcode
 ///
-/// \c varDecl(hasType(pointsTo(parenType(innerType(functionType()))))) matches
-/// \c ptr_to_func but not \c ptr_to_array.
+/// The matcher
+/// \matcher{varDecl(hasType(pointsTo(parenType(innerType(functionType())))))}
+///   matches \match{type=name$ptr_to_func} but not
+///   \nomatch{type=name$ptr_to_array}.
 ///
 /// Usable as: Matcher<ParenType>
 AST_TYPE_TRAVERSE_MATCHER(innerType, getInnerType,
@@ -7327,11 +9272,12 @@ extern const AstTypeMatcher<BlockPointerType> blockPointerType;
 /// Matches member pointer types.
 /// Given
 /// \code
-///   struct A { int i; }
-///   A::* ptr = A::i;
+///   struct A { int i; };
+///   int A::* ptr = &A::i;
 /// \endcode
-/// memberPointerType()
-///   matches "A::* ptr"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{memberPointerType()}
+/// matches \match{type=typestr$int struct A::*}.
 extern const AstTypeMatcher<MemberPointerType> memberPointerType;
 
 /// Matches pointer types, but does not match Objective-C object pointer
@@ -7339,16 +9285,24 @@ extern const AstTypeMatcher<MemberPointerType> memberPointerType;
 ///
 /// Given
 /// \code
-///   int *a;
-///   int &b = *a;
-///   int c = 5;
+///   typedef int* int_ptr;
+///   void foo(char *str,
+///            int val,
+///            int *val_ptr,
+///            int_ptr not_a_ptr,
+///            int_ptr *ptr);
+/// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{parmVarDecl(hasType(pointerType()))}
+/// matches \match{char *str}, \match{int *val_ptr} and
+/// \match{int_ptr *ptr}.
 ///
+/// \code
 ///   @interface Foo
 ///   @end
 ///   Foo *f;
 /// \endcode
-/// pointerType()
-///   matches "int *a", but does not match "Foo *f".
+/// \compile_args{-ObjC}
 extern const AstTypeMatcher<PointerType> pointerType;
 
 /// Matches an Objective-C object pointer type, which is different from
@@ -7362,8 +9316,10 @@ extern const AstTypeMatcher<PointerType> pointerType;
 ///   @end
 ///   Foo *f;
 /// \endcode
-/// pointerType()
-///   matches "Foo *f", but does not match "int *a".
+/// \compile_args{-ObjC}
+/// The matcher \matcher{pointerType()}
+/// matches \match{type=typestr$Foo *}, but does not match
+/// \nomatch{type=typestr$int *}.
 extern const AstTypeMatcher<ObjCObjectPointerType> objcObjectPointerType;
 
 /// Matches both lvalue and rvalue reference types.
@@ -7378,13 +9334,18 @@ extern const AstTypeMatcher<ObjCObjectPointerType> objcObjectPointerType;
 ///   auto &&f = 2;
 ///   int g = 5;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// \c referenceType() matches the types of \c b, \c c, \c d, \c e, and \c f.
+/// The matcher \matcher{referenceType()} matches the type
+/// \match{type=typestr$int &} of \c b , the type \match{type=typestr$int &&} of
+/// \c c, the type
+/// \match{type=typestr$auto &} \c d, and the type
+/// \match{type=typestr;count=2$auto &&} of \c e and \c f.
 extern const AstTypeMatcher<ReferenceType> referenceType;
 
 /// Matches lvalue reference types.
 ///
-/// Given:
+/// Given
 /// \code
 ///   int *a;
 ///   int &b = *a;
@@ -7394,14 +9355,17 @@ extern const AstTypeMatcher<ReferenceType> referenceType;
 ///   auto &&f = 2;
 ///   int g = 5;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// \c lValueReferenceType() matches the types of \c b, \c d, and \c e. \c e is
-/// matched since the type is deduced as int& by reference collapsing rules.
+/// The matcher \matcher{lValueReferenceType()} matches the type
+/// \match{type=typestr$int &} of \c b and the type \match{type=typestr$auto &}
+/// of \c d.
+/// FIXME: figure out why auto changechange matches twice
 extern const AstTypeMatcher<LValueReferenceType> lValueReferenceType;
 
 /// Matches rvalue reference types.
 ///
-/// Given:
+/// Given
 /// \code
 ///   int *a;
 ///   int &b = *a;
@@ -7411,9 +9375,11 @@ extern const AstTypeMatcher<LValueReferenceType> lValueReferenceType;
 ///   auto &&f = 2;
 ///   int g = 5;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// \c rValueReferenceType() matches the types of \c c and \c f. \c e is not
-/// matched as it is deduced to int& by reference collapsing rules.
+/// The matcher \matcher{rValueReferenceType()} matches the type
+/// \match{type=typestr$int &&} of \c c and the type
+/// \match{type=typestr;count=2$auto &&} of \c f.
 extern const AstTypeMatcher<RValueReferenceType> rValueReferenceType;
 
 /// Narrows PointerType (and similar) matchers to those where the
@@ -7422,11 +9388,15 @@ extern const AstTypeMatcher<RValueReferenceType> rValueReferenceType;
 /// Given
 /// \code
 ///   int *a;
-///   int const *b;
-///   float const *f;
+///   const int *b;
+///   int * const c = nullptr;
+///   const float *f;
 /// \endcode
-/// pointerType(pointee(isConstQualified(), isInteger()))
-///   matches "int const *b"
+/// \compile_args{-std=c++11-or-later,c23-or-later}
+/// The matcher \matcher{pointerType(pointee(isConstQualified(), isInteger()))}
+/// matches \match{type=typestr$const int *},
+/// but does not match \nomatch{type=typestr$int * const}
+/// or \nomatch{type=typestr$const float *}.
 ///
 /// Usable as: Matcher<BlockPointerType>, Matcher<MemberPointerType>,
 ///   Matcher<PointerType>, Matcher<ReferenceType>
@@ -7440,9 +9410,10 @@ AST_TYPELOC_TRAVERSE_MATCHER_DECL(
 /// Given
 /// \code
 ///   typedef int X;
+///   X x = 0;
 /// \endcode
-/// typedefType()
-///   matches "typedef int X"
+/// The matcher \matcher{typedefType()}
+/// matches \match{type=typestr$X}.
 extern const AstTypeMatcher<TypedefType> typedefType;
 
 /// Matches qualified types when the qualifier is applied via a macro.
@@ -7453,8 +9424,12 @@ extern const AstTypeMatcher<TypedefType> typedefType;
 ///   typedef void (CDECL *X)();
 ///   typedef void (__attribute__((cdecl)) *Y)();
 /// \endcode
-/// macroQualifiedType()
-///   matches the type of the typedef declaration of \c X but not \c Y.
+/// The matcher \matcher{macroQualifiedType()}
+/// matches the type \match{type=typestr;std=c++,c23-or-later$CDECL void
+/// (void)} of the typedef declaration of \c X , unless when in C98-C17, there
+/// \match{type=typestr;std=c17-or-earlier$CDECL void ()},
+/// but it does not match the type
+/// \nomatch{type=typestr$__attribute((cdecl)) void ()} of \c Y .
 extern const AstTypeMatcher<MacroQualifiedType> macroQualifiedType;
 
 /// Matches enum types.
@@ -7467,9 +9442,11 @@ extern const AstTypeMatcher<MacroQualifiedType> macroQualifiedType;
 ///   C c;
 ///   S s;
 /// \endcode
-//
-/// \c enumType() matches the type of the variable declarations of both \c c and
-/// \c s.
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{enumType()} matches the type
+/// \match{type=typestr$enum C} of \c c ,
+/// and the type \match{type=typestr$enum S} of \c s .
 extern const AstTypeMatcher<EnumType> enumType;
 
 /// Matches template specialization types.
@@ -7479,12 +9456,16 @@ extern const AstTypeMatcher<EnumType> enumType;
 ///   template <typename T>
 ///   class C { };
 ///
-///   template class C<int>;  // A
-///   C<char> var;            // B
+///   template class C<int>;
+///   C<int> intvar;
+///   C<char> charvar;
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
 ///
-/// \c templateSpecializationType() matches the type of the explicit
-/// instantiation in \c A and the type of the variable declaration in \c B.
+/// The matcher \matcher{templateSpecializationType()} matches the type
+/// \match{type=typestr$C<int>} of the explicit instantiation in \c A and the
+/// type \match{type=typestr$C<char>} of the variable declaration in
+/// \c B.
 extern const AstTypeMatcher<TemplateSpecializationType>
     templateSpecializationType;
 
@@ -7498,19 +9479,23 @@ extern const AstTypeMatcher<TemplateSpecializationType>
 ///
 ///   C c(123);
 /// \endcode
-/// \c deducedTemplateSpecializationType() matches the type in the declaration
-/// of the variable \c c.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++17-or-later}
+/// The matcher \matcher{deducedTemplateSpecializationType()} matches the type
+/// \match{type=typestr$C} of the declaration of the variable \c c.
 extern const AstTypeMatcher<DeducedTemplateSpecializationType>
     deducedTemplateSpecializationType;
 
 /// Matches types nodes representing unary type transformations.
 ///
-/// Given:
+/// Given
 /// \code
-///   typedef __underlying_type(T) type;
+///   template <typename T> struct A {
+///     typedef __underlying_type(T) type;
+///   };
 /// \endcode
-/// unaryTransformType()
-///   matches "__underlying_type(T)"
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{unaryTransformType()}
+/// matches \match{type=typestr$__underlying_type(T)}
 extern const AstTypeMatcher<UnaryTransformType> unaryTransformType;
 
 /// Matches record types (e.g. structs, classes).
@@ -7523,24 +9508,34 @@ extern const AstTypeMatcher<UnaryTransformType> unaryTransformType;
 ///   C c;
 ///   S s;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// \c recordType() matches the type of the variable declarations of both \c c
-/// and \c s.
+/// The matcher \matcher{recordType()} matches the type
+/// \match{type=typestr;count=3$class C} of the variable declaration of \c c and
+/// matches the type \match{type=typestr;count=3$struct S} of the variable
+/// declaration of \c s.
+/// Both of these types are matched three times, once for the type of the
+/// variable, once for the definition of the class, and once for the type of the
+/// injected class name.
 extern const AstTypeMatcher<RecordType> recordType;
 
 /// Matches tag types (record and enum types).
 ///
 /// Given
 /// \code
-///   enum E {};
+///   enum E { Ok };
 ///   class C {};
 ///
 ///   E e;
 ///   C c;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// \c tagType() matches the type of the variable declarations of both \c e
-/// and \c c.
+/// The matcher \matcher{tagType()} matches the type
+/// \match{type=typestr$enum E} of variable \c e and the type
+/// \match{type=typestr;count=3;std=c++$class C} three times, once for the type
+/// of the variable \c c , once for the type of the class definition and once of
+/// the type in the injected class name.
 extern const AstTypeMatcher<TagType> tagType;
 
 /// Matches types specified with an elaborated type keyword or with a
@@ -7555,16 +9550,22 @@ extern const AstTypeMatcher<TagType> tagType;
 ///   }
 ///   class C {};
 ///
-///   class C c;
+///   C c;
 ///   N::M::D d;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// \c elaboratedType() matches the type of the variable declarations of both
-/// \c c and \c d.
+/// The matcher \matcher{elaboratedType()} matches the type
+/// \match{type=typestr;count=3$C} three times. Once for the type of the
+/// variable \c c, once for the type of the class definition and once for the
+/// type in the injected class name. For \c{class D}, it matches
+/// \match{type=typestr$N::M::D} of variable \c d and its class definition and
+/// injected class name
+/// \match{type=typestr;count=2$D} one time respectively.
 extern const AstTypeMatcher<ElaboratedType> elaboratedType;
 
 /// Matches ElaboratedTypes whose qualifier, a NestedNameSpecifier,
-/// matches \c InnerMatcher if the qualifier exists.
+///   matches \c InnerMatcher if the qualifier exists.
 ///
 /// Given
 /// \code
@@ -7575,9 +9576,12 @@ extern const AstTypeMatcher<ElaboratedType> elaboratedType;
 ///   }
 ///   N::M::D d;
 /// \endcode
+/// \compile_args{-std=c++}
 ///
-/// \c elaboratedType(hasQualifier(hasPrefix(specifiesNamespace(hasName("N"))))
-/// matches the type of the variable declaration of \c d.
+/// The matcher
+/// \matcher{elaboratedType(hasQualifier(hasPrefix(specifiesNamespace(hasName("N")))))}
+///   matches the type \match{type=typestr$N::M::D} of the variable declaration
+///   of \c d.
 AST_MATCHER_P(ElaboratedType, hasQualifier,
               internal::Matcher<NestedNameSpecifier>, InnerMatcher) {
   if (const NestedNameSpecifier *Qualifier = Node.getQualifier())
@@ -7592,15 +9596,15 @@ AST_MATCHER_P(ElaboratedType, hasQualifier,
 /// \code
 ///   namespace N {
 ///     namespace M {
-///       class D {};
+///       enum E { Ok };
 ///     }
 ///   }
-///   N::M::D d;
+///   N::M::E e = N::M::Ok;
 /// \endcode
+/// \compile_args{-std=c++}
 ///
-/// \c elaboratedType(namesType(recordType(
-/// hasDeclaration(namedDecl(hasName("D")))))) matches the type of the variable
-/// declaration of \c d.
+/// The matcher \matcher{elaboratedType(namesType(enumType()))}
+/// matches the type \match{type=typestr$N::M::E} of the declaration of \c e .
 AST_MATCHER_P(ElaboratedType, namesType, internal::Matcher<QualType>,
               InnerMatcher) {
   return InnerMatcher.matches(Node.getNamedType(), Finder, Builder);
@@ -7614,8 +9618,10 @@ AST_MATCHER_P(ElaboratedType, namesType, internal::Matcher<QualType>,
 ///   using a::S;
 ///   S s;
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// \c usingType() matches the type of the variable declaration of \c s.
+/// The matcher \matcher{usingType()} matches the type \match{type=typestr$a::S}
+/// of the variable declaration of \c s.
 extern const AstTypeMatcher<UsingType> usingType;
 
 /// Matches types that represent the result of substituting a type for a
@@ -7625,11 +9631,18 @@ extern const AstTypeMatcher<UsingType> usingType;
 /// \code
 ///   template <typename T>
 ///   void F(T t) {
+///     T local;
 ///     int i = 1 + t;
 ///   }
+///   void f() {
+///     F(0);
+///   }
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
 ///
-/// \c substTemplateTypeParmType() matches the type of 't' but not '1'
+/// The matcher \matcher{varDecl(hasType(substTemplateTypeParmType()))}
+/// matches \match{T t} and \match{T local} for the substituted template type
+/// \c int in the instantiation of \c F .
 extern const AstTypeMatcher<SubstTemplateTypeParmType>
     substTemplateTypeParmType;
 
@@ -7643,46 +9656,66 @@ extern const AstTypeMatcher<SubstTemplateTypeParmType>
 ///   int i;
 ///   double j = F(i);
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
 ///
-/// \c substTemplateTypeParmType(hasReplacementType(type())) matches int
+/// The matcher \matcher{substTemplateTypeParmType(hasReplacementType(type()))}
+/// matches \match{type=typestr$int}.
 AST_TYPE_TRAVERSE_MATCHER(
     hasReplacementType, getReplacementType,
     AST_POLYMORPHIC_SUPPORTED_TYPES(SubstTemplateTypeParmType));
 
 /// Matches template type parameter types.
 ///
-/// Example matches T, but not int.
-///     (matcher = templateTypeParmType())
+/// Given
 /// \code
 ///   template <typename T> void f(int i);
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher \matcher{templateTypeParmType()} matches \match{type=typestr$T},
+/// but does not match \nomatch{type=typestr$int}.
 extern const AstTypeMatcher<TemplateTypeParmType> templateTypeParmType;
 
 /// Matches injected class name types.
 ///
-/// Example matches S s, but not S<T> s.
-///     (matcher = parmVarDecl(hasType(injectedClassNameType())))
+/// Given
 /// \code
 ///   template <typename T> struct S {
 ///     void f(S s);
 ///     void g(S<T> s);
 ///   };
 /// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++}
+/// The matcher
+/// \matcher{parmVarDecl(hasType(elaboratedType(namesType(injectedClassNameType()))))}
+/// matches \match{S s}, but not \notmatch{S<T> s}
 extern const AstTypeMatcher<InjectedClassNameType> injectedClassNameType;
 
 /// Matches decayed type
-/// Example matches i[] in declaration of f.
-///     (matcher = valueDecl(hasType(decayedType(hasDecayedType(pointerType())))))
-/// Example matches i[1].
-///     (matcher = expr(hasType(decayedType(hasDecayedType(pointerType())))))
 /// \code
 ///   void f(int i[]) {
 ///     i[1] = 0;
 ///   }
 /// \endcode
+/// The matcher
+/// \matcher{valueDecl(hasType(decayedType(hasDecayedType(pointerType()))))}
+/// matches \match{int i[]} in declaration of \c{f}.
+/// The matcher
+/// \matcher{expr(hasType(decayedType(hasDecayedType(pointerType()))))}
+/// matches \match{count=2$i} in \c{i[1]}.
+///
 extern const AstTypeMatcher<DecayedType> decayedType;
 
 /// Matches the decayed type, whoes decayed type matches \c InnerMatcher
+///
+/// Given
+/// \code
+///   void f(int i[]) {
+///     i[1] = 0;
+///   }
+/// \endcode
+///
+/// The matcher \matcher{parmVarDecl(hasType(decayedType()))}
+/// matches \match{int i[]}.
 AST_MATCHER_P(DecayedType, hasDecayedType, internal::Matcher<QualType>,
               InnerType) {
   return InnerType.matches(Node.getDecayedType(), Finder, Builder);
@@ -7699,9 +9732,10 @@ AST_MATCHER_P(DecayedType, hasDecayedType, internal::Matcher<QualType>,
 ///     }
 ///   }
 /// \endcode
+/// \compile_args{-std=c++}
 ///
-/// \c cxxRcordDecl(hasDeclContext(namedDecl(hasName("M")))) matches the
-/// declaration of \c class \c D.
+/// The matcher \matcher{cxxRecordDecl(hasDeclContext(namedDecl(hasName("M"))))}
+///   matches the declaration of \match{type=name$D}.
 AST_MATCHER_P(Decl, hasDeclContext, internal::Matcher<Decl>, InnerMatcher) {
   const DeclContext *DC = Node.getDeclContext();
   if (!DC) return false;
@@ -7719,17 +9753,47 @@ AST_MATCHER_P(Decl, hasDeclContext, internal::Matcher<Decl>, InnerMatcher) {
 ///   }
 ///   ns::A a;
 /// \endcode
-/// nestedNameSpecifier()
-///   matches "ns::" and both "A::"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{nestedNameSpecifier()}
+/// matches \match{type=name$ns} and both \match{type=name;count=2$A}
 extern const internal::VariadicAllOfMatcher<NestedNameSpecifier>
     nestedNameSpecifier;
 
 /// Same as \c nestedNameSpecifier but matches \c NestedNameSpecifierLoc.
+///
+/// Given
+/// \code
+///   namespace ns {
+///     struct A { static void f(); };
+///     void A::f() {}
+///     void g() { A::f(); }
+///   }
+///   ns::A a;
+/// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{nestedNameSpecifierLoc()} matches
+/// \match{count=2$A::} twice, and \match{ns::} once.
 extern const internal::VariadicAllOfMatcher<NestedNameSpecifierLoc>
     nestedNameSpecifierLoc;
 
 /// Matches \c NestedNameSpecifierLocs for which the given inner
 /// NestedNameSpecifier-matcher matches.
+///
+/// Given
+/// \code
+///   namespace ns {
+///     struct A { static void f(); };
+///     void A::f() {}
+///     void g() { A::f(); }
+///   }
+///   ns::A a;
+/// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{nestedNameSpecifierLoc(loc(specifiesType(
+/// hasDeclaration(namedDecl(hasName("A"))))))} matches \match{count=2$A::}
+/// twice.
 AST_MATCHER_FUNCTION_P_OVERLOAD(
     internal::BindableMatcher<NestedNameSpecifierLoc>, loc,
     internal::Matcher<NestedNameSpecifier>, InnerMatcher, 1) {
@@ -7746,10 +9810,11 @@ AST_MATCHER_FUNCTION_P_OVERLOAD(
 ///   struct A { struct B { struct C {}; }; };
 ///   A::B::C c;
 /// \endcode
-/// nestedNameSpecifier(specifiesType(
+/// \compile_args{-std=c++}
+/// The matcher \matcher{nestedNameSpecifier(specifiesType(
 ///   hasDeclaration(cxxRecordDecl(hasName("A")))
-/// ))
-///   matches "A::"
+/// ))}
+/// matches \match{type=name$A}.
 AST_MATCHER_P(NestedNameSpecifier, specifiesType,
               internal::Matcher<QualType>, InnerMatcher) {
   if (!Node.getAsType())
@@ -7765,9 +9830,10 @@ AST_MATCHER_P(NestedNameSpecifier, specifiesType,
 ///   struct A { struct B { struct C {}; }; };
 ///   A::B::C c;
 /// \endcode
-/// nestedNameSpecifierLoc(specifiesTypeLoc(loc(type(
-///   hasDeclaration(cxxRecordDecl(hasName("A")))))))
-///   matches "A::"
+/// \compile_args{-std=c++}
+/// The matcher \matcher{nestedNameSpecifierLoc(specifiesTypeLoc(loc(qualType(
+///   hasDeclaration(cxxRecordDecl(hasName("A")))))))}
+/// matches \match{A::}
 AST_MATCHER_P(NestedNameSpecifierLoc, specifiesTypeLoc,
               internal::Matcher<TypeLoc>, InnerMatcher) {
   return Node && Node.getNestedNameSpecifier()->getAsType() &&
@@ -7781,8 +9847,10 @@ AST_MATCHER_P(NestedNameSpecifierLoc, specifiesTypeLoc,
 ///   struct A { struct B { struct C {}; }; };
 ///   A::B::C c;
 /// \endcode
-/// nestedNameSpecifier(hasPrefix(specifiesType(asString("struct A")))) and
-///   matches "A::"
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{nestedNameSpecifier(hasPrefix(specifiesType(asString(
+/// "struct A"))))} matches \match{type=typestr$struct A::B}
 AST_MATCHER_P_OVERLOAD(NestedNameSpecifier, hasPrefix,
                        internal::Matcher<NestedNameSpecifier>, InnerMatcher,
                        0) {
@@ -7799,8 +9867,10 @@ AST_MATCHER_P_OVERLOAD(NestedNameSpecifier, hasPrefix,
 ///   struct A { struct B { struct C {}; }; };
 ///   A::B::C c;
 /// \endcode
-/// nestedNameSpecifierLoc(hasPrefix(loc(specifiesType(asString("struct A")))))
-///   matches "A::"
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{nestedNameSpecifierLoc(hasPrefix(loc(specifiesType(asString(
+/// "struct A")))))} matches \match{A::B::}.
 AST_MATCHER_P_OVERLOAD(NestedNameSpecifierLoc, hasPrefix,
                        internal::Matcher<NestedNameSpecifierLoc>, InnerMatcher,
                        1) {
@@ -7818,8 +9888,10 @@ AST_MATCHER_P_OVERLOAD(NestedNameSpecifierLoc, hasPrefix,
 ///   namespace ns { struct A {}; }
 ///   ns::A a;
 /// \endcode
-/// nestedNameSpecifier(specifiesNamespace(hasName("ns")))
-///   matches "ns::"
+/// \compile_args{-std=c++}
+/// The matcher
+/// \matcher{nestedNameSpecifier(specifiesNamespace(hasName("ns")))} matches
+/// \match{type=name$ns}.
 AST_MATCHER_P(NestedNameSpecifier, specifiesNamespace,
               internal::Matcher<NamespaceDecl>, InnerMatcher) {
   if (!Node.getAsNamespace())
@@ -7841,8 +9913,10 @@ AST_MATCHER_P(NestedNameSpecifier, specifiesNamespace,
 ///   #pragma omp declare simd
 ///   int min();
 /// \endcode
-/// attr()
-///   matches "nodiscard", "nonnull", "noinline", and the whole "#pragma" line.
+/// \compile_args{-fdeclspec;-fopenmp}
+/// The matcher \matcher{attr()}
+/// matches \match{nodiscard}, \match{nonnull}, \match{noinline}, and
+/// \match{declare simd}.
 extern const internal::VariadicAllOfMatcher<Attr> attr;
 
 /// Overloads for the \c equalsNode matcher.
@@ -7875,12 +9949,19 @@ AST_MATCHER_P_OVERLOAD(Type, equalsNode, const Type*, Other, 2) {
 ///
 /// Given
 /// \code
-///   switch (1) { case 1: case 2: default: switch (2) { case 3: case 4: ; } }
+///   void foo() {
+///     switch (1) { case 1: case 2: default: switch (2) { case 3: case 4: ; } }
+///   }
 /// \endcode
-/// switchStmt(forEachSwitchCase(caseStmt().bind("c"))).bind("s")
-///   matches four times, with "c" binding each of "case 1:", "case 2:",
-/// "case 3:" and "case 4:", and "s" respectively binding "switch (1)",
-/// "switch (1)", "switch (2)" and "switch (2)".
+/// The matcher
+/// \matcher{switchStmt(forEachSwitchCase(caseStmt().bind("c")))}
+/// matches four times, matching
+/// \match{count=2$switch (1) { case 1: case 2: default: switch (2) { case 3:
+/// case 4: ; } }} and
+/// \match{count=2$switch (2) { case 3: case 4: ; }}, with
+/// \matcher{type=sub$caseStmt()} matching each of \match{sub=c$case 1:},
+/// \match{sub=c$case 2:}, \match{sub=c$case 3:}
+/// and \match{sub=c$case 4:}.
 AST_MATCHER_P(SwitchStmt, forEachSwitchCase, internal::Matcher<SwitchCase>,
               InnerMatcher) {
   BoundNodesTreeBuilder Result;
@@ -7908,10 +9989,12 @@ AST_MATCHER_P(SwitchStmt, forEachSwitchCase, internal::Matcher<SwitchCase>,
 /// \code
 ///   class A { A() : i(42), j(42) {} int i; int j; };
 /// \endcode
-/// cxxConstructorDecl(forEachConstructorInitializer(
-///   forField(decl().bind("x"))
-/// ))
-///   will trigger two matches, binding for 'i' and 'j' respectively.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxConstructorDecl(forEachConstructorInitializer(
+///   forField(fieldDecl().bind("x"))))}
+/// matches the constructor of \match{type=name;count=2$A} twice, with
+/// \matcher{type=sub$fieldDecl()} matching \match{sub=field$i} and
+/// \match{sub=field$j} respectively.
 AST_MATCHER_P(CXXConstructorDecl, forEachConstructorInitializer,
               internal::Matcher<CXXCtorInitializer>, InnerMatcher) {
   BoundNodesTreeBuilder Result;
@@ -7939,7 +10022,10 @@ AST_MATCHER_P(CXXConstructorDecl, forEachConstructorInitializer,
 ///     S(S &&); // #3
 ///   };
 /// \endcode
-/// cxxConstructorDecl(isCopyConstructor()) will match #2, but not #1 or #3.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxConstructorDecl(isCopyConstructor())}
+/// matches \match{S(const S &)},
+/// but does not match \nomatch{S()} or \nomatch{S(S &&)}.
 AST_MATCHER(CXXConstructorDecl, isCopyConstructor) {
   return Node.isCopyConstructor();
 }
@@ -7954,7 +10040,10 @@ AST_MATCHER(CXXConstructorDecl, isCopyConstructor) {
 ///     S(S &&); // #3
 ///   };
 /// \endcode
-/// cxxConstructorDecl(isMoveConstructor()) will match #3, but not #1 or #2.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxConstructorDecl(isMoveConstructor())}
+/// matches \match{S(S &&)}
+/// but does not match \nomatch{S();} or \nomatch{S(S &&);}
 AST_MATCHER(CXXConstructorDecl, isMoveConstructor) {
   return Node.isMoveConstructor();
 }
@@ -7969,7 +10058,10 @@ AST_MATCHER(CXXConstructorDecl, isMoveConstructor) {
 ///     S(S &&); // #3
 ///   };
 /// \endcode
-/// cxxConstructorDecl(isDefaultConstructor()) will match #1, but not #2 or #3.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxConstructorDecl(isDefaultConstructor())}
+/// matches \match{S()}
+/// but does not match \nomatch{S(const S &);} or \nomatch{S(S &&);}.
 AST_MATCHER(CXXConstructorDecl, isDefaultConstructor) {
   return Node.isDefaultConstructor();
 }
@@ -7985,8 +10077,10 @@ AST_MATCHER(CXXConstructorDecl, isDefaultConstructor) {
 ///   };
 ///   S::S() : S(0) {} // #4
 /// \endcode
-/// cxxConstructorDecl(isDelegatingConstructor()) will match #3 and #4, but not
-/// #1 or #2.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{cxxConstructorDecl(isDelegatingConstructor())}
+/// matches \match{S(S &&) : S() {}} and \match{S::S() : S(0) {}},
+/// but does not match \nomatch{S()} or \nomatch{S(int)}.
 AST_MATCHER(CXXConstructorDecl, isDelegatingConstructor) {
   return Node.isDelegatingConstructor();
 }
@@ -8003,16 +10097,28 @@ AST_MATCHER(CXXConstructorDecl, isDelegatingConstructor) {
 ///     explicit S(double); // #2
 ///     operator int(); // #3
 ///     explicit operator bool(); // #4
-///     explicit(false) S(bool) // # 7
-///     explicit(true) S(char) // # 8
-///     explicit(b) S(S) // # 9
+///     explicit(false) S(bool); // # 7
+///     explicit(true) S(char); // # 8
+///     explicit(b) S(float); // # 9
 ///   };
-///   S(int) -> S<true> // #5
-///   explicit S(double) -> S<false> // #6
-/// \endcode
-/// cxxConstructorDecl(isExplicit()) will match #2 and #8, but not #1, #7 or #9.
-/// cxxConversionDecl(isExplicit()) will match #4, but not #3.
-/// cxxDeductionGuideDecl(isExplicit()) will match #6, but not #5.
+///   S(int) -> S<true>; // #5
+///   explicit S(double) -> S<false>; // #6
+/// \endcode
+/// \compile_args{-fno-delayed-template-parsing;-std=c++20-or-later}
+/// The matcher \matcher{cxxConstructorDecl(isExplicit())}
+/// matches \match{explicit S(double)}
+/// and \match{explicit(true) S(char)}
+/// but does not match \nomatch{S(int);}, \nomatch{explicit(false) S(bool);} or
+/// \nomatch{explicit(b) S(float)}
+/// The matcher \matcher{cxxConversionDecl(isExplicit())}
+/// matches \match{explicit operator bool()}
+/// but does not match \nomatch{operator int()}.
+/// The matcher \matcher{cxxDeductionGuideDecl(isExplicit())}
+/// matches the deduction guide \match{explicit S(double) -> S<false>},
+/// the implicit copy deduction candiate
+/// \match{type=typeofstr$auto (double) -> S<b>} and
+/// the implicitly generated deduction guide for \match{explicit(true) S(char)},
+/// but does not match \nomatch{S(int) -> S<true>}.
 AST_POLYMORPHIC_MATCHER(isExplicit, AST_POLYMORPHIC_SUPPORTED_TYPES(
                                         CXXConstructorDecl, CXXConversionDecl,
                                         CXXDeductionGuideDecl)) {
@@ -8030,16 +10136,28 @@ AST_POLYMORPHIC_MATCHER(isExplicit, AST_POLYMORPHIC_SUPPORTED_TYPES(
 ///     explicit S(double); // #2
 ///     operator int(); // #3
 ///     explicit operator bool(); // #4
-///     explicit(false) S(bool) // # 7
-///     explicit(true) S(char) // # 8
-///     explicit(b) S(S) // # 9
+///     explicit(false) S(bool); // # 7
+///     explicit(true) S(char); // # 8
+///     explicit(b) S(float); // # 9
 ///   };
-///   S(int) -> S<true> // #5
-///   explicit S(double) -> S<false> // #6
+///   S(int) -> S<true>; // #5
+///   explicit S(double) -> S<false>; // #6
 /// \endcode
-/// cxxConstructorDecl(hasExplicitSpecifier(constantExpr())) will match #7, #8 and #9, but not #1 or #2.
-/// cxxConversionDecl(hasExplicitSpecifier(constantExpr())) will not match #3 or #4.
-/// cxxDeductionGuideDecl(hasExplicitSpecifier(constantExpr())) will not match #5 or #6.
+/// \compile_args{-fno-delayed-template-parsing;-std=c++20-or-later}
+/// The matcher
+/// \matcher{cxxConstructorDecl(hasExplicitSpecifier(constantExpr()))} matches
+/// \match{explicit(false) S(bool)} and \match{explicit(true) S(char)},
+/// but does not match \nomatch{explicit(b) S(float)}, \nomatch{S(int)} or
+/// \nomatch{explicit S(double)}.
+/// The matcher
+/// \matcher{cxxConversionDecl(hasExplicitSpecifier(constantExpr()))} does not
+/// match \nomatch{operator int()} or \nomatch{explicit operator bool()}.
+/// Matcher
+/// The matcher
+/// \matcher{cxxDeductionGuideDecl(hasExplicitSpecifier(declRefExpr()))}
+/// matches the implicitly generated deduction guide
+/// \match{type=typeofstr$auto (float) -> S<b>} of the constructor
+/// \c{explicit(b) S(float)}.
 AST_MATCHER_P(FunctionDecl, hasExplicitSpecifier, internal::Matcher<Expr>,
               InnerMatcher) {
   ExplicitSpecifier ES = ExplicitSpecifier::getFromDecl(&Node);
@@ -8063,9 +10181,10 @@ AST_MATCHER_P(FunctionDecl, hasExplicitSpecifier, internal::Matcher<Expr>,
 ///   }
 ///   inline int Foo = 5;
 /// \endcode
-/// functionDecl(isInline()) will match ::f().
-/// namespaceDecl(isInline()) will match n::m.
-/// varDecl(isInline()) will match Foo;
+/// \compile_args{-std=c++}
+/// The matcher \matcher{functionDecl(isInline())} matches \match{type=name$f}.
+/// The matcher \matcher{namespaceDecl(isInline())} matches \match{type=name$m}.
+/// The matcher \matcher{varDecl(isInline())} matches \match{type=name$Foo}
 AST_POLYMORPHIC_MATCHER(isInline, AST_POLYMORPHIC_SUPPORTED_TYPES(NamespaceDecl,
                                                                   FunctionDecl,
                                                                   VarDecl)) {
@@ -8088,7 +10207,9 @@ AST_POLYMORPHIC_MATCHER(isInline, AST_POLYMORPHIC_SUPPORTED_TYPES(NamespaceDecl,
 ///   namespace {} // #1
 ///   }
 /// \endcode
-/// namespaceDecl(isAnonymous()) will match #1 but not ::n.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{namespaceDecl(isAnonymous())}
+/// matches \match{namespace {}}, but not \nomatch{namespace n}.
 AST_MATCHER(NamespaceDecl, isAnonymous) {
   return Node.isAnonymousNamespace();
 }
@@ -8113,7 +10234,9 @@ AST_MATCHER(NamespaceDecl, isAnonymous) {
 ///     }
 ///   }
 /// \endcode
-/// cxxRecordDecl(hasName("vector"), isInStdNamespace()) will match only #1.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(hasName("vector"), isInStdNamespace())}
+/// matches \match{class vector {}} inside of namespace std.
 AST_MATCHER(Decl, isInStdNamespace) { return Node.isInStdNamespace(); }
 
 /// Matches declarations in an anonymous namespace.
@@ -8130,12 +10253,15 @@ AST_MATCHER(Decl, isInStdNamespace) { return Node.isInStdNamespace(); }
 ///   namespace {
 ///     class vector {}; // #2
 ///     namespace foo {
-///       class vector{}; // #3
+///       class vector {}; // #3
 ///     }
 ///   }
 /// \endcode
-/// cxxRecordDecl(hasName("vector"), isInAnonymousNamespace()) will match
-/// #1, #2 and #3.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(hasName("vector"),
+///                         isInAnonymousNamespace())}
+/// matches \match{type=name;count=6$vector},
+/// twice per declaration at #1, #2 and #3.
 AST_MATCHER(Decl, isInAnonymousNamespace) {
   return Node.isInAnonymousNamespace();
 }
@@ -8145,10 +10271,13 @@ AST_MATCHER(Decl, isInAnonymousNamespace) {
 ///
 /// Given
 /// \code
-///   switch (1) { case 1: case 1+1: case 3 ... 4: ; }
+///   void foo() {
+///     switch (1) { case 1: break; case 1+1: break; case 3 ... 4: break; }
+///   }
 /// \endcode
-/// caseStmt(hasCaseConstant(integerLiteral()))
-///   matches "case 1:"
+/// The matcher
+/// \matcher{caseStmt(hasCaseConstant(constantExpr(has(integerLiteral()))))}
+/// matches \match{case 1: break}.
 AST_MATCHER_P(CaseStmt, hasCaseConstant, internal::Matcher<Expr>,
               InnerMatcher) {
   if (Node.getRHS())
@@ -8161,11 +10290,14 @@ AST_MATCHER_P(CaseStmt, hasCaseConstant, internal::Matcher<Expr>,
 ///
 /// Given
 /// \code
-///   __attribute__((device)) void f() { ... }
+///   __attribute__((device)) void f() {}
 /// \endcode
-/// decl(hasAttr(clang::attr::CUDADevice)) matches the function declaration of
-/// f. If the matcher is used from clang-query, attr::Kind parameter should be
-/// passed as a quoted string. e.g., hasAttr("attr::CUDADevice").
+/// \compile_args{--cuda-gpu-arch=sm_70}
+/// The matcher \matcher{decl(hasAttr(clang::attr::CUDADevice))}
+/// matches \match{type=name$f}.
+/// If the matcher is used from clang-query, attr::Kind
+/// parameter should be passed as a quoted string. e.g.,
+/// \c hasAttr("attr::CUDADevice").
 AST_MATCHER_P(Decl, hasAttr, attr::Kind, AttrKind) {
   for (const auto *Attr : Node.attrs()) {
     if (Attr->getKind() == AttrKind)
@@ -8178,12 +10310,14 @@ AST_MATCHER_P(Decl, hasAttr, attr::Kind, AttrKind) {
 ///
 /// Given
 /// \code
-///   return a + b;
+///   int foo(int a, int b) {
+///     return a + b;
+///   }
 /// \endcode
-/// hasReturnValue(binaryOperator())
-///   matches 'return a + b'
-/// with binaryOperator()
-///   matching 'a + b'
+/// The matcher
+/// \matcher{returnStmt(hasReturnValue(binaryOperator().bind("op")))} matches
+/// \match{return a + b}, with \matcher{type=sub$binaryOperator()} matching
+/// \match{sub=op$a + b}.
 AST_MATCHER_P(ReturnStmt, hasReturnValue, internal::Matcher<Expr>,
               InnerMatcher) {
   if (const auto *RetValue = Node.getRetValue())
@@ -8193,18 +10327,25 @@ AST_MATCHER_P(ReturnStmt, hasReturnValue, internal::Matcher<Expr>,
 
 /// Matches CUDA kernel call expression.
 ///
-/// Example matches,
+/// Given
 /// \code
-///   kernel<<<i,j>>>();
+///   __global__ void kernel() {}
+///   void f() {
+///     kernel<<<32,32>>>();
+///   }
 /// \endcode
+/// \compile_args{--cuda-gpu-arch=sm_70}
+/// The matcher \matcher{cudaKernelCallExpr()}
+/// matches \match{kernel<<<i, k>>>()}
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CUDAKernelCallExpr>
     cudaKernelCallExpr;
 
 /// Matches expressions that resolve to a null pointer constant, such as
 /// GNU's __null, C++11's nullptr, or C's NULL macro.
 ///
-/// Given:
+/// Given
 /// \code
+///   #define NULL 0
 ///   void *v1 = NULL;
 ///   void *v2 = nullptr;
 ///   void *v3 = __null; // GNU extension
@@ -8212,9 +10353,14 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, CUDAKernelCallExpr>
 ///   int *ip = 0;
 ///   int i = 0;
 /// \endcode
-/// expr(nullPointerConstant())
-///   matches the initializer for v1, v2, v3, cp, and ip. Does not match the
-///   initializer for i.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{expr(nullPointerConstant())}
+/// matches the initializer \match{NULL} of v1,
+/// matches the initializer \match{nullptr} of v2,
+/// matches the initializer \match{__null} of v3,
+/// matches the initializer \match{0} of cp and
+/// matches the initializer \match{0} of ip,
+/// but does not match the initializer \nomatch{i} of i.
 AST_MATCHER_FUNCTION(internal::Matcher<Expr>, nullPointerConstant) {
   return anyOf(
       gnuNullExpr(), cxxNullPtrLiteralExpr(),
@@ -8223,7 +10369,7 @@ AST_MATCHER_FUNCTION(internal::Matcher<Expr>, nullPointerConstant) {
 
 /// Matches the DecompositionDecl the binding belongs to.
 ///
-/// For example, in:
+/// Given
 /// \code
 /// void foo()
 /// {
@@ -8233,12 +10379,10 @@ AST_MATCHER_FUNCTION(internal::Matcher<Expr>, nullPointerConstant) {
 ///     f = 42;
 /// }
 /// \endcode
-/// The matcher:
-/// \code
-///   bindingDecl(hasName("f"),
-///                 forDecomposition(decompositionDecl())
-/// \endcode
-/// matches 'f' in 'auto &[f, s, t]'.
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{bindingDecl(hasName("f"),
+///                 forDecomposition(decompositionDecl()))}
+/// matches \match{type=name$f} in 'auto &[f, s, t]'.
 AST_MATCHER_P(BindingDecl, forDecomposition, internal::Matcher<ValueDecl>,
               InnerMatcher) {
   if (const ValueDecl *VD = Node.getDecomposedDecl())
@@ -8248,7 +10392,7 @@ AST_MATCHER_P(BindingDecl, forDecomposition, internal::Matcher<ValueDecl>,
 
 /// Matches the Nth binding of a DecompositionDecl.
 ///
-/// For example, in:
+/// Given
 /// \code
 /// void foo()
 /// {
@@ -8258,12 +10402,10 @@ AST_MATCHER_P(BindingDecl, forDecomposition, internal::Matcher<ValueDecl>,
 ///     f = 42;
 /// }
 /// \endcode
-/// The matcher:
-/// \code
-///   decompositionDecl(hasBinding(0,
-///   bindingDecl(hasName("f").bind("fBinding"))))
-/// \endcode
-/// matches the decomposition decl with 'f' bound to "fBinding".
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{decompositionDecl(hasBinding(0,
+///   bindingDecl(hasName("f")).bind("fBinding")))}
+/// matches \match{auto &[f, s, t] = arr} with 'f' bound to "fBinding".
 AST_MATCHER_P2(DecompositionDecl, hasBinding, unsigned, N,
                internal::Matcher<BindingDecl>, InnerMatcher) {
   if (Node.bindings().size() <= N)
@@ -8283,11 +10425,10 @@ AST_MATCHER_P2(DecompositionDecl, hasBinding, unsigned, N,
 ///     f = 42;
 /// }
 /// \endcode
-/// The matcher:
-/// \code
-///   decompositionDecl(hasAnyBinding(bindingDecl(hasName("f").bind("fBinding"))))
-/// \endcode
-/// matches the decomposition decl with 'f' bound to "fBinding".
+/// \compile_args{-std=c++11-or-later}
+/// The matcher
+///  \matcher{decompositionDecl(hasAnyBinding(bindingDecl(hasName("f")).bind("fBinding")))}
+/// matches \match{auto &[f, s, t] = arr} with 'f' bound to "fBinding".
 AST_MATCHER_P(DecompositionDecl, hasAnyBinding, internal::Matcher<BindingDecl>,
               InnerMatcher) {
   return llvm::any_of(Node.bindings(), [&](const auto *Binding) {
@@ -8299,19 +10440,23 @@ AST_MATCHER_P(DecompositionDecl, hasAnyBinding, internal::Matcher<BindingDecl>,
 ///
 /// Deprecated. Use forCallable() to correctly handle the situation when
 /// the declaration is not a function (but a block or an Objective-C method).
-/// forFunction() not only fails to take non-functions into account but also
-/// may match the wrong declaration in their presence.
+/// The matcher \c forFunction() not only fails to take non-functions
+/// into account but also may match the wrong declaration in their presence.
 ///
-/// Given:
+/// Given
 /// \code
-/// F& operator=(const F& o) {
-///   std::copy_if(o.begin(), o.end(), begin(), [](V v) { return v > 0; });
-///   return *this;
-/// }
+///   struct F {
+///     F& operator=(const F& other) {
+///       []() { return 42 == 42; };
+///       return *this;
+///     }
+///   };
 /// \endcode
-/// returnStmt(forFunction(hasName("operator=")))
-///   matches 'return *this'
-///   but does not match 'return v > 0'
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{returnStmt(forFunction(hasName("operator=")))}
+/// matches \match{return *this}
+/// but does not match \nomatch{return 42 == 42}.
 AST_MATCHER_P(Stmt, forFunction, internal::Matcher<FunctionDecl>,
               InnerMatcher) {
   const auto &Parents = Finder->getASTContext().getParents(Node);
@@ -8339,30 +10484,34 @@ AST_MATCHER_P(Stmt, forFunction, internal::Matcher<FunctionDecl>,
 /// Matches declaration of the function, method, or block the statement
 /// belongs to.
 ///
-/// Given:
+/// Given
 /// \code
-/// F& operator=(const F& o) {
-///   std::copy_if(o.begin(), o.end(), begin(), [](V v) { return v > 0; });
-///   return *this;
-/// }
+/// struct F {
+///   F& operator=(const F& other) {
+///     []() { return 42 == 42; };
+///     return *this;
+///   }
+/// };
 /// \endcode
-/// returnStmt(forCallable(functionDecl(hasName("operator="))))
-///   matches 'return *this'
-///   but does not match 'return v > 0'
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{returnStmt(forFunction(hasName("operator=")))}
+/// matches \match{return *this}
+/// but does not match \nomatch{return 42 == 42}.
 ///
-/// Given:
+/// Given
 /// \code
-/// -(void) foo {
+/// void foo {
 ///   int x = 1;
 ///   dispatch_sync(queue, ^{ int y = 2; });
 /// }
 /// \endcode
-/// declStmt(forCallable(objcMethodDecl()))
-///   matches 'int x = 1'
-///   but does not match 'int y = 2'.
-/// whereas declStmt(forCallable(blockDecl()))
-///   matches 'int y = 2'
-///   but does not match 'int x = 1'.
+/// \compile_args{-ObjC}
+/// The matcher \matcher{declStmt(forCallable(objcMethodDecl()))}
+/// matches \match{int x = 1}
+/// but does not match \nomatch{int y = 2}.
+/// The matcher \matcher{declStmt(forCallable(blockDecl()))}
+/// matches \match{int y = 2}
+/// but does not match \nomatch{int x = 1}.
 AST_MATCHER_P(Stmt, forCallable, internal::Matcher<Decl>, InnerMatcher) {
   const auto &Parents = Finder->getASTContext().getParents(Node);
 
@@ -8396,73 +10545,93 @@ AST_MATCHER_P(Stmt, forCallable, internal::Matcher<Decl>, InnerMatcher) {
 
 /// Matches a declaration that has external formal linkage.
 ///
-/// Example matches only z (matcher = varDecl(hasExternalFormalLinkage()))
+/// Given
 /// \code
 /// void f() {
-///   int x;
-///   static int y;
+///   int a;
+///   static int b;
 /// }
-/// int z;
+/// int c;
+/// static int d;
 /// \endcode
+/// The matcher \matcher{varDecl(hasExternalFormalLinkage())}
+/// matches \match{int c},
+/// but not \nomatch{int a}, \nomatch{static int b} or \nomatch{int d}.
 ///
-/// Example matches f() because it has external formal linkage despite being
-/// unique to the translation unit as though it has internal likage
-/// (matcher = functionDecl(hasExternalFormalLinkage()))
-///
+/// Given
 /// \code
-/// namespace {
-/// void f() {}
-/// }
+///   namespace {
+///     void f() {}
+///   }
+///   void g() {}
+///   static void h() {}
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{functionDecl(hasExternalFormalLinkage())}
+/// matches \match{void g() {}}, but not \nomatch{void f() {}} or
+/// \nomatch{static void h() {}}.
 AST_MATCHER(NamedDecl, hasExternalFormalLinkage) {
   return Node.hasExternalFormalLinkage();
 }
 
 /// Matches a declaration that has default arguments.
 ///
-/// Example matches y (matcher = parmVarDecl(hasDefaultArgument()))
+/// Given
 /// \code
-/// void x(int val) {}
-/// void y(int val = 0) {}
+///   void x(int val) {}
+///   void y(int val = 0) {}
 /// \endcode
+/// \compile_args{-std=c++}
+///
+/// The matcher \matcher{parmVarDecl(hasDefaultArgument())}
+/// matches \match{int val = 0}.
 ///
 /// Deprecated. Use hasInitializer() instead to be able to
 /// match on the contents of the default argument.  For example:
 ///
+/// Given
 /// \code
-/// void x(int val = 7) {}
-/// void y(int val = 42) {}
+///   void x(int val = 7) {}
+///   void y(int val = 42) {}
 /// \endcode
-/// parmVarDecl(hasInitializer(integerLiteral(equals(42))))
-///   matches the parameter of y
+/// \compile_args{-std=c++}
 ///
-/// A matcher such as
-///   parmVarDecl(hasInitializer(anything()))
-/// is equivalent to parmVarDecl(hasDefaultArgument()).
+/// The matcher
+/// \matcher{parmVarDecl(hasInitializer(integerLiteral(equals(42))))},
+/// matches \match{int val = 42}.
 AST_MATCHER(ParmVarDecl, hasDefaultArgument) {
   return Node.hasDefaultArg();
 }
 
 /// Matches array new expressions.
 ///
-/// Given:
+/// Given
 /// \code
+///   struct MyClass { int x; };
 ///   MyClass *p1 = new MyClass[10];
 /// \endcode
-/// cxxNewExpr(isArray())
-///   matches the expression 'new MyClass[10]'.
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxNewExpr(isArray())}
+/// matches \match{new MyClass[10]}.
 AST_MATCHER(CXXNewExpr, isArray) {
   return Node.isArray();
 }
 
 /// Matches placement new expression arguments.
 ///
-/// Given:
+/// Given
 /// \code
-///   MyClass *p1 = new (Storage, 16) MyClass();
+///   void *operator new(decltype(sizeof(void*)), int, void*);
+///   struct MyClass { int x; };
+///   unsigned char Storage[sizeof(MyClass) * 10];
+///   MyClass *p1 = new (16, Storage) MyClass();
 /// \endcode
-/// cxxNewExpr(hasPlacementArg(1, integerLiteral(equals(16))))
-///   matches the expression 'new (Storage, 16) MyClass()'.
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{cxxNewExpr(hasPlacementArg(0,
+///                       integerLiteral(equals(16))))}
+/// matches \match{new (16, Storage) MyClass()}.
 AST_MATCHER_P2(CXXNewExpr, hasPlacementArg, unsigned, Index,
                internal::Matcher<Expr>, InnerMatcher) {
   return Node.getNumPlacementArgs() > Index &&
@@ -8471,12 +10640,17 @@ AST_MATCHER_P2(CXXNewExpr, hasPlacementArg, unsigned, Index,
 
 /// Matches any placement new expression arguments.
 ///
-/// Given:
+/// Given
 /// \code
+///   void* operator new(decltype(sizeof(void*)), void*);
+///   struct MyClass { int x; };
+///   unsigned char Storage[sizeof(MyClass) * 10];
 ///   MyClass *p1 = new (Storage) MyClass();
 /// \endcode
-/// cxxNewExpr(hasAnyPlacementArg(anything()))
-///   matches the expression 'new (Storage, 16) MyClass()'.
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher \matcher{cxxNewExpr(hasAnyPlacementArg(anything()))}
+/// matches \match{new (Storage) MyClass()}.
 AST_MATCHER_P(CXXNewExpr, hasAnyPlacementArg, internal::Matcher<Expr>,
               InnerMatcher) {
   return llvm::any_of(Node.placement_arguments(), [&](const Expr *Arg) {
@@ -8486,12 +10660,18 @@ AST_MATCHER_P(CXXNewExpr, hasAnyPlacementArg, internal::Matcher<Expr>,
 
 /// Matches array new expressions with a given array size.
 ///
-/// Given:
+/// Given
 /// \code
+///   void* operator new(decltype(sizeof(void*)));
+///   struct MyClass { int x; };
 ///   MyClass *p1 = new MyClass[10];
 /// \endcode
-/// cxxNewExpr(hasArraySize(integerLiteral(equals(10))))
-///   matches the expression 'new MyClass[10]'.
+/// \compile_args{-std=c++11-or-later}
+///
+/// The matcher
+/// \matcher{cxxNewExpr(hasArraySize(
+///             ignoringImplicit(integerLiteral(equals(10)))))}
+/// matches \match{new MyClass[10]}.
 AST_MATCHER_P(CXXNewExpr, hasArraySize, internal::Matcher<Expr>, InnerMatcher) {
   return Node.isArray() && *Node.getArraySize() &&
          InnerMatcher.matches(**Node.getArraySize(), Finder, Builder);
@@ -8499,33 +10679,42 @@ AST_MATCHER_P(CXXNewExpr, hasArraySize, internal::Matcher<Expr>, InnerMatcher) {
 
 /// Matches a class declaration that is defined.
 ///
-/// Example matches x (matcher = cxxRecordDecl(hasDefinition()))
+/// Given
 /// \code
 /// class x {};
 /// class y;
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{cxxRecordDecl(hasDefinition())}
+/// matches \match{class x {}}
 AST_MATCHER(CXXRecordDecl, hasDefinition) {
   return Node.hasDefinition();
 }
 
 /// Matches C++11 scoped enum declaration.
 ///
-/// Example matches Y (matcher = enumDecl(isScoped()))
+/// Given
 /// \code
 /// enum X {};
 /// enum class Y {};
 /// \endcode
+/// \compile_args{-std=c++}
+/// The matcher \matcher{enumDecl(isScoped())}
+/// matches \match{enum class Y {}}
 AST_MATCHER(EnumDecl, isScoped) {
   return Node.isScoped();
 }
 
 /// Matches a function declared with a trailing return type.
 ///
-/// Example matches Y (matcher = functionDecl(hasTrailingReturn()))
+/// Given
 /// \code
 /// int X() {}
 /// auto Y() -> int {}
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
+/// The matcher \matcher{functionDecl(hasTrailingReturn())}
+/// matches \match{auto Y() -> int {}}.
 AST_MATCHER(FunctionDecl, hasTrailingReturn) {
   if (const auto *F = Node.getType()->getAs<FunctionProtoType>())
     return F->hasTrailingReturn();
@@ -8544,7 +10733,6 @@ AST_MATCHER(FunctionDecl, hasTrailingReturn) {
 /// appear in the C++17 AST.
 ///
 /// Given
-///
 /// \code
 /// struct H {};
 /// H G();
@@ -8552,9 +10740,11 @@ AST_MATCHER(FunctionDecl, hasTrailingReturn) {
 ///   H D = G();
 /// }
 /// \endcode
+/// \compile_args{-std=c++11-or-later}
 ///
-/// ``varDecl(hasInitializer(ignoringElidableConstructorCall(callExpr())))``
-/// matches ``H D = G()`` in C++11 through C++17 (and beyond).
+/// The matcher
+/// \matcher{varDecl(hasInitializer(ignoringElidableConstructorCall(callExpr())))}
+/// matches \match{H D = G()}.
 AST_MATCHER_P(Expr, ignoringElidableConstructorCall, internal::Matcher<Expr>,
               InnerMatcher) {
   // E tracks the node that we are examining.
@@ -8585,15 +10775,21 @@ AST_MATCHER_P(Expr, ignoringElidableConstructorCall, internal::Matcher<Expr>,
 /// Matches any ``#pragma omp`` executable directive.
 ///
 /// Given
-///
 /// \code
-///   #pragma omp parallel
-///   #pragma omp parallel default(none)
-///   #pragma omp taskyield
+///   void foo() {
+///     #pragma omp parallel
+///       {}
+///     #pragma omp parallel default(none)
+///       {
+///         #pragma omp taskyield
+///       }
+///   }
 /// \endcode
-///
-/// ``ompExecutableDirective()`` matches ``omp parallel``,
-/// ``omp parallel default(none)`` and ``omp taskyield``.
+/// \compile_args{-fopenmp}
+/// The matcher \matcher{ompExecutableDirective()}
+/// matches \match{#pragma omp parallel},
+/// \match{#pragma omp parallel default(none)}
+/// and \match{#pragma omp taskyield}.
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, OMPExecutableDirective>
     ompExecutableDirective;
 
@@ -8601,15 +10797,18 @@ extern const internal::VariadicDynCastAllOfMatcher<Stmt, OMPExecutableDirective>
 /// i.e., directives that can't have a structured block.
 ///
 /// Given
-///
 /// \code
-///   #pragma omp parallel
-///   {}
-///   #pragma omp taskyield
+///   void foo() {
+///     #pragma omp parallel
+///     {
+///       #pragma omp taskyield
+///     }
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// ``ompExecutableDirective(isStandaloneDirective()))`` matches
-/// ``omp taskyield``.
+/// The matcher \matcher{ompExecutableDirective(isStandaloneDirective())}
+/// matches \match{#pragma omp taskyield}.
 AST_MATCHER(OMPExecutableDirective, isStandaloneDirective) {
   return Node.isStandaloneDirective();
 }
@@ -8620,15 +10819,20 @@ AST_MATCHER(OMPExecutableDirective, isStandaloneDirective) {
 /// If it is, it will never match.
 ///
 /// Given
-///
 /// \code
-///    #pragma omp parallel
-///    ;
-///    #pragma omp parallel
-///    {}
+///   void foo() {
+///     #pragma omp parallel
+///     ;
+///     #pragma omp parallel
+///     {}
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// ``ompExecutableDirective(hasStructuredBlock(nullStmt()))`` will match ``;``
+/// The matcher
+/// \matcher{ompExecutableDirective(hasStructuredBlock(nullStmt().bind("stmt")))}
+/// matches \match{#pragma omp parallel},
+/// with \matcher{type=sub$stmtt()} matching \match{sub=stmt${}}.
 AST_MATCHER_P(OMPExecutableDirective, hasStructuredBlock,
               internal::Matcher<Stmt>, InnerMatcher) {
   if (Node.isStandaloneDirective())
@@ -8639,14 +10843,18 @@ AST_MATCHER_P(OMPExecutableDirective, hasStructuredBlock,
 /// Matches any clause in an OpenMP directive.
 ///
 /// Given
-///
 /// \code
+///   void foo() {
 ///   #pragma omp parallel
+///     ;
 ///   #pragma omp parallel default(none)
+///     ;
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// ``ompExecutableDirective(hasAnyClause(anything()))`` matches
-/// ``omp parallel default(none)``.
+/// The matcher \matcher{ompExecutableDirective(hasAnyClause(anything()))}
+/// matches \match{#pragma omp parallel default(none)}.
 AST_MATCHER_P(OMPExecutableDirective, hasAnyClause,
               internal::Matcher<OMPClause>, InnerMatcher) {
   ArrayRef<OMPClause *> Clauses = Node.clauses();
@@ -8658,33 +10866,53 @@ AST_MATCHER_P(OMPExecutableDirective, hasAnyClause,
 /// Matches OpenMP ``default`` clause.
 ///
 /// Given
-///
 /// \code
-///   #pragma omp parallel default(none)
-///   #pragma omp parallel default(shared)
-///   #pragma omp parallel default(private)
-///   #pragma omp parallel default(firstprivate)
-///   #pragma omp parallel
+///   void foo() {
+///     #pragma omp parallel default(none)
+///       ;
+///     #pragma omp parallel default(shared)
+///       ;
+///     #pragma omp parallel default(private)
+///       ;
+///     #pragma omp parallel default(firstprivate)
+///       ;
+///     #pragma omp parallel
+///       ;
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// ``ompDefaultClause()`` matches ``default(none)``, ``default(shared)``,
-/// `` default(private)`` and ``default(firstprivate)``
+/// The matcher
+/// \matcher{ompExecutableDirective(hasAnyClause(ompDefaultClause()))} matches
+/// \match{#pragma omp parallel default(none)},
+/// \match{#pragma omp parallel default(shared)},
+/// \match{#pragma omp parallel default(private)} and
+/// \match{#pragma omp parallel default(firstprivate)}.
 extern const internal::VariadicDynCastAllOfMatcher<OMPClause, OMPDefaultClause>
     ompDefaultClause;
 
 /// Matches if the OpenMP ``default`` clause has ``none`` kind specified.
 ///
 /// Given
-///
 /// \code
-///   #pragma omp parallel
-///   #pragma omp parallel default(none)
-///   #pragma omp parallel default(shared)
-///   #pragma omp parallel default(private)
-///   #pragma omp parallel default(firstprivate)
+///   void foo() {
+///     #pragma omp parallel
+///       ;
+///     #pragma omp parallel default(none)
+///       ;
+///     #pragma omp parallel default(shared)
+///       ;
+///     #pragma omp parallel default(private)
+///       ;
+///     #pragma omp parallel default(firstprivate)
+///       ;
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// ``ompDefaultClause(isNoneKind())`` matches only ``default(none)``.
+/// The matcher
+/// \matcher{ompExecutableDirective(hasAnyClause(ompDefaultClause(isNoneKind())))}
+/// matches only \match{#pragma omp parallel default(none)}.
 AST_MATCHER(OMPDefaultClause, isNoneKind) {
   return Node.getDefaultKind() == llvm::omp::OMP_DEFAULT_none;
 }
@@ -8692,16 +10920,25 @@ AST_MATCHER(OMPDefaultClause, isNoneKind) {
 /// Matches if the OpenMP ``default`` clause has ``shared`` kind specified.
 ///
 /// Given
-///
 /// \code
-///   #pragma omp parallel
-///   #pragma omp parallel default(none)
+///   void foo() {
+///     #pragma omp parallel
+///       ;
+///     #pragma omp parallel default(none)
+///       ;
 ///   #pragma omp parallel default(shared)
+///       ;
 ///   #pragma omp parallel default(private)
+///       ;
 ///   #pragma omp parallel default(firstprivate)
+///       ;
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// ``ompDefaultClause(isSharedKind())`` matches only ``default(shared)``.
+/// The matcher
+/// \matcher{ompExecutableDirective(hasAnyClause(ompDefaultClause(isSharedKind())))}
+/// matches \match{#pragma omp parallel default(shared)}.
 AST_MATCHER(OMPDefaultClause, isSharedKind) {
   return Node.getDefaultKind() == llvm::omp::OMP_DEFAULT_shared;
 }
@@ -8710,17 +10947,25 @@ AST_MATCHER(OMPDefaultClause, isSharedKind) {
 /// specified.
 ///
 /// Given
-///
 /// \code
-///   #pragma omp parallel
+///   void foo() {
+///     #pragma omp parallel
+///       ;
 ///   #pragma omp parallel default(none)
+///       ;
 ///   #pragma omp parallel default(shared)
+///       ;
 ///   #pragma omp parallel default(private)
+///       ;
 ///   #pragma omp parallel default(firstprivate)
+///       ;
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// ``ompDefaultClause(isPrivateKind())`` matches only
-/// ``default(private)``.
+/// The matcher
+/// \matcher{ompExecutableDirective(hasAnyClause(ompDefaultClause(isPrivateKind())))}
+/// matches \match{#pragma omp parallel default(private)}.
 AST_MATCHER(OMPDefaultClause, isPrivateKind) {
   return Node.getDefaultKind() == llvm::omp::OMP_DEFAULT_private;
 }
@@ -8729,17 +10974,25 @@ AST_MATCHER(OMPDefaultClause, isPrivateKind) {
 /// specified.
 ///
 /// Given
-///
 /// \code
-///   #pragma omp parallel
-///   #pragma omp parallel default(none)
-///   #pragma omp parallel default(shared)
-///   #pragma omp parallel default(private)
-///   #pragma omp parallel default(firstprivate)
+///   void foo() {
+///     #pragma omp parallel
+///       ;
+///     #pragma omp parallel default(none)
+///       ;
+///     #pragma omp parallel default(shared)
+///       ;
+///     #pragma omp parallel default(private)
+///       ;
+///     #pragma omp parallel default(firstprivate)
+///       ;
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// ``ompDefaultClause(isFirstPrivateKind())`` matches only
-/// ``default(firstprivate)``.
+/// The matcher
+/// \matcher{ompExecutableDirective(hasAnyClause(ompDefaultClause(isFirstPrivateKind())))}
+/// matches \match{#pragma omp parallel default(firstprivate)}.
 AST_MATCHER(OMPDefaultClause, isFirstPrivateKind) {
   return Node.getDefaultKind() == llvm::omp::OMP_DEFAULT_firstprivate;
 }
@@ -8748,15 +11001,23 @@ AST_MATCHER(OMPDefaultClause, isFirstPrivateKind) {
 /// clause kind.
 ///
 /// Given
-///
 /// \code
-///   #pragma omp parallel
-///   #pragma omp parallel for
-///   #pragma omp          for
+///   void foo() {
+///     #pragma omp parallel
+///       ;
+///     #pragma omp parallel for
+///       for (int i = 0; i < 10; ++i) {}
+///     #pragma omp          for
+///       for (int i = 0; i < 10; ++i) {}
+///   }
 /// \endcode
+/// \compile_args{-fopenmp}
 ///
-/// `ompExecutableDirective(isAllowedToContainClause(OMPC_default))`` matches
-/// ``omp parallel`` and ``omp parallel for``.
+/// The matcher
+/// \matcher{ompExecutableDirective(isAllowedToContainClauseKind(
+/// OpenMPClauseKind::OMPC_default))}
+/// matches \match{#pragma omp parallel}
+/// and \match{#pragma omp parallel for}.
 ///
 /// If the matcher is use from clang-query, ``OpenMPClauseKind`` parameter
 /// should be passed as a quoted string. e.g.,
diff --git a/clang/unittests/ASTMatchers/ASTMatchersTest.h b/clang/unittests/ASTMatchers/ASTMatchersTest.h
index ad2f5f355621c..89df18331d4ed 100644
--- a/clang/unittests/ASTMatchers/ASTMatchersTest.h
+++ b/clang/unittests/ASTMatchers/ASTMatchersTest.h
@@ -9,12 +9,46 @@
 #ifndef LLVM_CLANG_UNITTESTS_ASTMATCHERS_ASTMATCHERSTEST_H
 #define LLVM_CLANG_UNITTESTS_ASTMATCHERS_ASTMATCHERSTEST_H
 
+#include "clang/AST/APValue.h"
+#include "clang/AST/ASTTypeTraits.h"
+#include "clang/AST/Decl.h"
+#include "clang/AST/DeclCXX.h"
+#include "clang/AST/DeclTemplate.h"
+#include "clang/AST/Expr.h"
+#include "clang/AST/NestedNameSpecifier.h"
+#include "clang/AST/Stmt.h"
+#include "clang/AST/Type.h"
+#include "clang/AST/TypeLoc.h"
 #include "clang/ASTMatchers/ASTMatchFinder.h"
+#include "clang/ASTMatchers/ASTMatchers.h"
+#include "clang/Basic/Diagnostic.h"
+#include "clang/Basic/DiagnosticIDs.h"
+#include "clang/Basic/LLVM.h"
+#include "clang/Basic/SourceLocation.h"
 #include "clang/Frontend/ASTUnit.h"
+#include "clang/Serialization/PCHContainerOperations.h"
 #include "clang/Testing/CommandLineArgs.h"
 #include "clang/Testing/TestClangConfig.h"
+#include "clang/Tooling/ArgumentsAdjusters.h"
+#include "clang/Tooling/FixIt.h"
 #include "clang/Tooling/Tooling.h"
+#include "llvm/ADT/STLExtras.h"
+#include "llvm/ADT/StringExtras.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Casting.h"
+#include "llvm/Support/ErrorHandling.h"
+#include "llvm/Support/FormatVariadic.h"
+#include "llvm/Support/VirtualFileSystem.h"
+#include "llvm/Support/raw_ostream.h"
 #include "gtest/gtest.h"
+#include <cstddef>
+#include <iterator>
+#include <memory>
+#include <optional>
+#include <string>
+#include <type_traits>
+#include <utility>
+#include <vector>
 
 namespace clang {
 namespace ast_matchers {
@@ -293,7 +327,8 @@ template <typename T>
 testing::AssertionResult matchAndVerifyResultConditionally(
     const Twine &Code, const T &AMatcher,
     std::unique_ptr<BoundNodesCallback> FindResultVerifier, bool ExpectResult,
-    ArrayRef<std::string> Args = {}, StringRef Filename = "input.cc") {
+    ArrayRef<std::string> Args = {}, StringRef Filename = "input.cc",
+    const FileContentMappings &VirtualMappedFiles = {}) {
   bool VerifiedResult = false;
   MatchFinder Finder;
   VerifyMatch VerifyVerifiedResult(std::move(FindResultVerifier),
@@ -310,7 +345,9 @@ testing::AssertionResult matchAndVerifyResultConditionally(
   // choices that we made above.
   llvm::copy(Args, std::back_inserter(CompileArgs));
 
-  if (!runToolOnCodeWithArgs(Factory->create(), Code, CompileArgs, Filename)) {
+  if (!runToolOnCodeWithArgs(
+          Factory->create(), Code, CompileArgs, Filename, "clang-tool",
+          std::make_shared<PCHContainerOperations>(), VirtualMappedFiles)) {
     return testing::AssertionFailure() << "Parsing error in \"" << Code << "\"";
   }
   if (!VerifiedResult && ExpectResult) {
@@ -324,7 +361,9 @@ testing::AssertionResult matchAndVerifyResultConditionally(
   VerifiedResult = false;
   SmallString<256> Buffer;
   std::unique_ptr<ASTUnit> AST(buildASTFromCodeWithArgs(
-      Code.toStringRef(Buffer), CompileArgs, Filename));
+      Code.toStringRef(Buffer), CompileArgs, Filename, "clang-tool",
+      std::make_shared<PCHContainerOperations>(),
+      tooling::getClangStripDependencyFileAdjuster(), VirtualMappedFiles));
   if (!AST.get())
     return testing::AssertionFailure()
            << "Parsing error in \"" << Code << "\" while building AST";
@@ -433,6 +472,373 @@ template <typename T> class VerifyIdIsBoundTo : public BoundNodesCallback {
   std::string Name;
 };
 
+namespace detail {
+template <typename T>
+using hasDump_t = decltype(std::declval<const T &>().dump());
+template <typename T>
+constexpr bool hasDump = llvm::is_detected<hasDump_t, T>::value;
+
+template <typename T>
+using hasGetSourceRange_t =
+    decltype(std::declval<const T &>().getSourceRange());
+template <typename T>
+constexpr bool hasGetSourceRange =
+    llvm::is_detected<hasGetSourceRange_t, T>::value;
+
+template <typename T, std::enable_if_t<hasGetSourceRange<T>, bool> = true>
+std::optional<std::string> getText(const T *const Node,
+                                   const ASTContext &Context) {
+  return tooling::fixit::getText(*Node, Context).str();
+}
+inline std::optional<std::string> getText(const Attr *const Attribute,
+                                          const ASTContext &) {
+  return Attribute->getSpelling();
+}
+inline std::optional<std::string> getText(const void *const,
+                                          const ASTContext &) {
+  return std::nullopt;
+}
+
+template <typename T>
+auto getSourceRange(const T *const Node)
+    -> std::optional<decltype(Node->getSourceRange())> {
+  return Node->getSourceRange();
+}
+inline std::optional<SourceRange> getSourceRange(const void *const) {
+  return std::nullopt;
+}
+
+template <typename T>
+auto getLocation(const T *const Node)
+    -> std::optional<decltype(Node->getLocation())> {
+  return Node->getLocation();
+}
+inline std::optional<SourceLocation> getLocation(const void *const) {
+  return std::nullopt;
+}
+
+template <typename T>
+auto getBeginLoc(const T *const Node)
+    -> std::optional<decltype(Node->getBeginLoc())> {
+  return Node->getBeginLoc();
+}
+inline std::optional<SourceLocation> getBeginLoc(const void *const) {
+  return std::nullopt;
+}
+
+inline std::optional<SourceLocation>
+getLocOfTagDeclFromType(const Type *const Node) {
+  if (Node->isArrayType())
+    if (const auto *const AType = Node->getPointeeOrArrayElementType()) {
+      return getLocOfTagDeclFromType(AType);
+    }
+  if (const auto *const TDecl = Node->getAsTagDecl()) {
+    return TDecl->getLocation();
+  }
+  return std::nullopt;
+}
+inline std::optional<SourceLocation>
+getLocOfTagDeclFromType(const void *const Node) {
+  return std::nullopt;
+}
+
+template <typename T>
+auto getExprLoc(const T *const Node)
+    -> std::optional<decltype(Node->getBeginLoc())> {
+  return Node->getBeginLoc();
+}
+inline std::optional<SourceLocation> getExprLoc(const void *const) {
+  return std::nullopt;
+}
+
+// Provides a string for test failures to show what was matched.
+template <typename T>
+static std::optional<std::string>
+getNodeDescription(const T *const Node, const ASTContext *const Context) {
+  if constexpr (std::is_same_v<T, QualType>) {
+    return Node->getAsString();
+  }
+  if constexpr (std::is_base_of_v<NamedDecl, T>) {
+    return Node->getNameAsString();
+  }
+  if constexpr (std::is_base_of_v<Type, T>) {
+    return QualType{Node, 0}.getAsString();
+  }
+
+  return detail::getText(Node, *Context);
+}
+
+template <typename T>
+bool shouldIgnoreNode(const T *const Node, const ASTContext &Context) {
+  if (const auto Range = detail::getSourceRange(Node); Range.has_value()) {
+    if (Range->isInvalid() ||
+        !Context.getSourceManager().isInMainFile(Range->getBegin()))
+      return true;
+  } else if (const auto Loc = detail::getExprLoc(Node); Loc.has_value()) {
+    if (Loc->isInvalid() || !Context.getSourceManager().isInMainFile(*Loc))
+      return true;
+  } else if (const auto Loc = detail::getLocation(Node); Loc.has_value()) {
+    if (Loc->isInvalid() || !Context.getSourceManager().isInMainFile(*Loc))
+      return true;
+  } else if (const auto Loc = detail::getBeginLoc(Node); Loc.has_value()) {
+    if (Loc->isInvalid() || !Context.getSourceManager().isInMainFile(*Loc))
+      return true;
+  } else if (const auto Loc = detail::getLocOfTagDeclFromType(Node);
+             Loc.has_value()) {
+    if (Loc->isInvalid() || !Context.getSourceManager().isInMainFile(*Loc))
+      return true;
+  }
+  return false;
+}
+} // namespace detail
+
+enum class MatchKind {
+  Code,
+  Name,
+  TypeStr,
+  TypeOfStr,
+};
+
+inline llvm::StringRef toString(const MatchKind Kind) {
+  switch (Kind) {
+  case MatchKind::Code:
+    return "Code";
+  case MatchKind::Name:
+    return "Name";
+  case MatchKind::TypeStr:
+    return "TypeStr";
+  case MatchKind::TypeOfStr:
+    return "TypeOfStr";
+  }
+  llvm_unreachable("Unhandled MatchKind");
+}
+
+template <typename T> class VerifyBoundNodeMatch : public BoundNodesCallback {
+public:
+  class Match {
+  public:
+    Match(const MatchKind Kind, std::string MatchString,
+          const size_t MatchCount = 1)
+        : Kind(Kind), MatchString(std::move(MatchString)),
+          RemainingMatches(MatchCount) {}
+
+    bool shouldRemoveMatched(const T *const Node) {
+      --RemainingMatches;
+      return RemainingMatches == 0U;
+    }
+
+    template <typename U>
+    static std::optional<std::string>
+    getMatchText(const U *const Node, const ASTContext &Context,
+                 const MatchKind Kind, const bool EmitFailures = true) {
+      if constexpr (std::is_same_v<U, NestedNameSpecifier>) {
+        if (const IdentifierInfo *const Info = Node->getAsIdentifier())
+          return Info->getName().str();
+        if (const NamespaceDecl *const NS = Node->getAsNamespace())
+          return getMatchText(NS, Context, Kind, EmitFailures);
+        if (const NamespaceAliasDecl *const Alias = Node->getAsNamespaceAlias())
+          return getMatchText(Alias, Context, Kind, EmitFailures);
+        if (const CXXRecordDecl *const RDecl = Node->getAsRecordDecl())
+          return getMatchText(RDecl, Context, Kind, EmitFailures);
+        if (const Type *const RDecl = Node->getAsType())
+          return getMatchText(RDecl, Context, Kind, EmitFailures);
+      }
+
+      switch (Kind) {
+      case MatchKind::Code:
+        return detail::getText(Node, Context);
+      case MatchKind::Name:
+        return getNameText(Node, EmitFailures);
+      case MatchKind::TypeStr:
+        return getTypeStrText(Node, EmitFailures);
+      case MatchKind::TypeOfStr:
+        return getTypeOfStrText(Node, EmitFailures);
+      }
+    }
+
+    bool isMatch(const T *const Node, const ASTContext &Context) const {
+      if (const auto OptMatchText = getMatchText(Node, Context, Kind))
+        return *OptMatchText == MatchString;
+
+      return false;
+    }
+
+    std::string getAsString() const {
+      return llvm::formatv("MatchKind: {0}, MatchString: '{1}', "
+                           "RemainingMatches: {2}",
+                           toString(Kind), MatchString, RemainingMatches)
+          .str();
+    }
+
+    MatchKind getMatchKind() const { return Kind; }
+    llvm::StringRef getMatchString() const { return MatchString; }
+
+  private:
+    template <typename U>
+    static std::optional<std::string>
+    getNameText(const U *const Node, const bool EmitFailures = true) {
+      if constexpr (std::is_base_of_v<Decl, U>) {
+        if (const auto *const NDecl = llvm::dyn_cast<NamedDecl>(Node))
+          return NDecl->getNameAsString();
+        if (EmitFailures)
+          ADD_FAILURE() << "'MatchKind::Name' requires 'U' to be a'NamedDecl'.";
+      }
+
+      if (EmitFailures)
+        ADD_FAILURE() << "'MatchKind::Name' requires 'U' to be a "
+                         "'NamedDecl', but 'U' is not derived from 'Decl'.";
+      return std::nullopt;
+    }
+
+    template <typename U>
+    static std::optional<std::string>
+    getTypeStrText(const U *const Node, const bool EmitFailures = true) {
+      if constexpr (std::is_base_of_v<Type, U>)
+        return QualType(Node, 0).getAsString();
+      if constexpr (std::is_base_of_v<Decl, U>)
+        if (const auto *const TDecl = llvm::dyn_cast<TypeDecl>(Node))
+          return getTypeStrText(TDecl->getTypeForDecl());
+
+      if (EmitFailures)
+        ADD_FAILURE() << "Match kind is 'TypeStr', but node of type 'U' is "
+                         "not handled.";
+      return std::nullopt;
+    }
+
+    template <typename U>
+    static std::optional<std::string>
+    getTypeOfStrText(const U *const Node, const bool EmitFailures = true) {
+      if constexpr (std::is_base_of_v<Decl, U>) {
+        if (const auto *const VDecl = llvm::dyn_cast<ValueDecl>(Node))
+          return VDecl->getType().getAsString();
+      } else if constexpr (std::is_base_of_v<Expr, U>)
+        return Node->getType().getAsString();
+
+      if (EmitFailures)
+        ADD_FAILURE() << "Match kind is 'TypeOfStr', but node of type 'U' is "
+                         "not handled.";
+      return std::nullopt;
+    }
+
+    MatchKind Kind;
+    std::string MatchString;
+    size_t RemainingMatches;
+  };
+
+  VerifyBoundNodeMatch(std::string Id, std::vector<Match> Matches)
+      : Id(std::move(Id)), ExpectedMatches(std::move(Matches)),
+        Matches(ExpectedMatches) {}
+
+  bool run(const BoundNodes *const Nodes, ASTContext *const Context) override {
+    const auto *const Node = Nodes->getNodeAs<T>(Id);
+    if (Node == nullptr) {
+      ADD_FAILURE() << "Expected Id '" << Id << "' to be bound to 'T'.";
+      return true;
+    }
+
+    if constexpr (std::is_base_of_v<Decl, T>)
+      if (const auto *const NDecl = llvm::dyn_cast<NamedDecl>(Node))
+        if (const auto *Identifier = NDecl->getIdentifier();
+            Identifier != nullptr && Identifier->getBuiltinID() > 0)
+          return true;
+
+    if (detail::shouldIgnoreNode(Node, *Context)) {
+      return false;
+    }
+
+    const auto Iter = llvm::find_if(Matches, [Node, Context](const Match &M) {
+      return M.isMatch(Node, *Context);
+    });
+    if (Iter == Matches.end()) {
+      const auto NodeText =
+          detail::getNodeDescription(Node, Context).value_or("<unknown>");
+      const auto IsMultilineNodeText = NodeText.find('\n') != std::string::npos;
+      ADD_FAILURE() << "No match of node '" << (IsMultilineNodeText ? "\n" : "")
+                    << NodeText << (IsMultilineNodeText ? "\n" : "")
+                    << "' was expected.\n"
+                    << "No match with remaining matches:"
+                    << getMatchComparisonText(Matches, Node, *Context)
+                    << "Match strings of Node for possible intended matches:"
+                    << getPossibleMatchStrings(Node, *Context)
+                    << "Already found matches:"
+                    << getMatchesAsString(FoundMatches) << "Expected matches:"
+                    << getMatchesAsString(ExpectedMatches);
+      if constexpr (detail::hasDump<T>)
+        Node->dump();
+      return true;
+    }
+
+    if (Iter->shouldRemoveMatched(Node)) {
+      FoundMatches.push_back(*Iter);
+      Matches.erase(Iter);
+    }
+
+    return true;
+  }
+
+  void onEndOfTranslationUnit() override {
+    if (!ExpectedMatches.empty() && Matches.size() == ExpectedMatches.size())
+      ADD_FAILURE() << "No matches were found.\n"
+                    << "Expected matches:"
+                    << getMatchesAsString(ExpectedMatches);
+    else
+      EXPECT_TRUE(Matches.empty())
+          << "Not all expected matches were found.\n"
+          << "Remaining matches:" << getMatchesAsString(Matches)
+          << "Already found matches:" << getMatchesAsString(FoundMatches)
+          << "Expected matches:" << getMatchesAsString(ExpectedMatches);
+
+    Matches = ExpectedMatches;
+    FoundMatches.clear();
+
+    EXPECT_TRUE(FoundMatches.empty());
+  }
+
+private:
+  static std::string getMatchesAsString(const std::vector<Match> &Matches) {
+    if (Matches.empty())
+      return " none\n";
+    std::string FormattedMatches{"\n"};
+    for (const Match &M : Matches)
+      FormattedMatches += "\t" + M.getAsString() + ",\n";
+
+    return FormattedMatches;
+  }
+  static std::string getMatchComparisonText(const std::vector<Match> &Matches,
+                                            const T *const Node,
+                                            const ASTContext &Context) {
+    if (Matches.empty())
+      return " none\n";
+    std::string MatchStrings{"\n"};
+    for (const Match &M : Matches)
+      MatchStrings += llvm::formatv(
+          "\tMatchKind: {0}: '{1}' vs '{2}',\n", toString(M.getMatchKind()),
+          Match::getMatchText(Node, Context, M.getMatchKind(), false)
+              .value_or("<unknown>"),
+          M.getMatchString());
+
+    return MatchStrings;
+  }
+
+  static std::string getPossibleMatchStrings(const T *Node,
+                                             const ASTContext &Context) {
+    std::string MatchStrings{"\n"};
+    for (const auto Kind : {MatchKind::Code, MatchKind::Name,
+                            MatchKind::TypeStr, MatchKind::TypeOfStr})
+      MatchStrings +=
+          llvm::formatv("\tMatchKind:  {0}: '{1}',\n", toString(Kind),
+                        Match::getMatchText(Node, Context, Kind, false)
+                            .value_or("<unknown>"))
+              .str();
+    return MatchStrings;
+  }
+
+  const std::string Id;
+  const std::vector<Match> ExpectedMatches;
+  std::vector<Match> Matches;
+  std::vector<Match> FoundMatches{};
+};
+
 class ASTMatchersTest : public ::testing::Test,
                         public ::testing::WithParamInterface<TestClangConfig> {
 protected:
@@ -453,6 +859,40 @@ class ASTMatchersTest : public ::testing::Test,
   }
 };
 
+class ASTMatchersDocTest
+    : public ::testing::Test,
+      public ::testing::WithParamInterface<TestClangConfig> {
+protected:
+  template <typename T>
+  testing::AssertionResult
+  matches(const Twine &Code, const T &AMatcher,
+          std::unique_ptr<BoundNodesCallback> FindResultVerifier,
+          const ArrayRef<std::string> CompileArgs = {},
+          const FileContentMappings &VirtualMappedFiles = {}) {
+    const TestClangConfig &TestConfig = GetParam();
+
+    auto Args = TestConfig.getCommandLineArgs();
+    Args.insert(Args.end(), CompileArgs.begin(), CompileArgs.end());
+    return clang::ast_matchers::matchAndVerifyResultConditionally(
+        Code, AMatcher, std::move(FindResultVerifier), /*ExpectMatch=*/true,
+        Args, getFilenameForTesting(TestConfig.Language), VirtualMappedFiles);
+  }
+
+  template <typename T>
+  testing::AssertionResult
+  notMatches(const Twine &Code, const T &AMatcher,
+             std::unique_ptr<BoundNodesCallback> FindResultVerifier,
+             const ArrayRef<std::string> CompileArgs = {},
+             const FileContentMappings &VirtualMappedFiles = {}) {
+    const TestClangConfig &TestConfig = GetParam();
+
+    auto Args = TestConfig.getCommandLineArgs();
+    Args.insert(Args.begin(), CompileArgs.begin(), CompileArgs.end());
+    return clang::ast_matchers::matchAndVerifyResultConditionally(
+        Code, AMatcher, std::move(FindResultVerifier), /*ExpectMatch=*/false,
+        Args, getFilenameForTesting(TestConfig.Language), VirtualMappedFiles);
+  }
+};
 } // namespace ast_matchers
 } // namespace clang
 
diff --git a/clang/unittests/ASTMatchers/CMakeLists.txt b/clang/unittests/ASTMatchers/CMakeLists.txt
index 6a1e629d81b65..4867a2e39150b 100644
--- a/clang/unittests/ASTMatchers/CMakeLists.txt
+++ b/clang/unittests/ASTMatchers/CMakeLists.txt
@@ -4,11 +4,26 @@ set(LLVM_LINK_COMPONENTS
   TargetParser
   )
 
+add_custom_command(
+  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/ASTMatchersDocTests.cpp
+  COMMAND
+    ${CLANG_SOURCE_DIR}/utils/generate_ast_matcher_doc_tests.py ARGS
+    --input-file
+    ${CLANG_SOURCE_DIR}/include/clang/ASTMatchers/ASTMatchers.h
+    --output-file
+    ${CMAKE_CURRENT_BINARY_DIR}/ASTMatchersDocTests.cpp
+  MAIN_DEPENDENCY
+    ${CLANG_SOURCE_DIR}/include/clang/ASTMatchers/ASTMatchers.h
+  DEPENDS
+    ${CLANG_SOURCE_DIR}/utils/generate_ast_matcher_doc_tests.py ARGS
+)
+
 add_clang_unittest(ASTMatchersTests
   ASTMatchersInternalTest.cpp
   ASTMatchersNodeTest.cpp
   ASTMatchersNarrowingTest.cpp
   ASTMatchersTraversalTest.cpp
+  ${CMAKE_CURRENT_BINARY_DIR}/ASTMatchersDocTests.cpp
   GtestMatchersTest.cpp
   )
 
diff --git a/clang/utils/generate_ast_matcher_doc_tests.py b/clang/utils/generate_ast_matcher_doc_tests.py
new file mode 100755
index 0000000000000..3f05a63a79e87