From 8c5f948beae22f1b65b8c29b4ba2ac1e3b7dacb5 Mon Sep 17 00:00:00 2001
From: Manuel Klimek <klimek@google.com>
Date: Fri, 21 Jun 2013 09:59:59 +0000
Subject: [PATCH] Improve documentation for AST matchers.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@184538 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/LibASTMatchersReference.html | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/LibASTMatchersReference.html b/docs/LibASTMatchersReference.html
index 50ff38edfa..7b70f11845 100644
--- a/docs/LibASTMatchersReference.html
+++ b/docs/LibASTMatchersReference.html
@@ -57,6 +57,18 @@ find all matchers that can be used to match on Stmt nodes.</p>
 <p>The exception to that rule are matchers that can match on any node. Those
 are marked with a * and are listed in the beginning of each category.</p>
 
+<p>Note that the categorization of matchers is a great help when you combine
+them into matcher expressions. You will usually want to form matcher expressions
+that read like english sentences by alternating between node matchers and
+narrowing or traversal matchers, like this:
+<pre>
+recordDecl(hasDescendant(
+    ifStmt(hasTrueExpression(
+        expr(hasDescendant(
+            ifStmt()))))))
+</pre>
+</p>
+
 <!-- ======================================================================= -->
 <h2 id="decl-matchers">Node Matchers</h2>
 <!-- ======================================================================= -->
@@ -73,6 +85,17 @@ and implicitly act as allOf matchers.</p>
 bind the matched node to the given string, to be later retrieved from the
 match callback.</p>
 
+<p>It is important to remember that the arguments to node matchers are
+predicates on the same node, just with additional information about the type.
+This is often useful to make matcher expression more readable by inlining bind
+calls into redundant node matchers inside another node matcher:
+<pre>
+// This binds the CXXRecordDecl to "id", as the decl() matcher will stay on
+// the same node.
+recordDecl(decl().bind("id"), hasName("::MyClass"))
+</pre>
+</p>
+
 <table>
 <tr style="text-align:left"><th>Return type</th><th>Name</th><th>Parameters</th></tr>
 <!-- START_DECL_MATCHERS -->
-- 
2.40.0