go/ast/inspector: add commentary about Cursor API

It's too bad we added Inspector.PreorderSeq and All just
before the Cursor API made them redundant.

Change-Id: I7ad53e9a9863f4ff7336a3aee3a1583c5c1b5e69
Reviewed-on: https://go-review.googlesource.com/c/tools/+/733181
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Griesemer <gri@google.com>

Author: adonovan

go/ast/inspector/inspector.go

@@ -87,7 +87,7 @@ type event struct {
 // Type can be recovered from the sole bit in typ.
 // [Tried this, wasn't faster. --adonovan]
 
-// Preorder visits all the nodes of the files supplied to New in
+// Preorder visits all the nodes of the files supplied to [New] in
 // depth-first order. It calls f(n) for each node n before it visits
 // n's children.
 //
@@ -133,7 +133,7 @@ func (in *Inspector) Preorder(types []ast.Node, f func(ast.Node)) {
 	}
 }
 
-// Nodes visits the nodes of the files supplied to New in depth-first
+// Nodes visits the nodes of the files supplied to [New] in depth-first
 // order. It calls f(n, true) for each node n before it visits n's
 // children. If f returns true, Nodes invokes f recursively for each
 // of the non-nil children of the node, followed by a call of

go/ast/inspector/iter.go

@@ -12,13 +12,31 @@ import (
 )
 
 // PreorderSeq returns an iterator that visits all the
-// nodes of the files supplied to New in depth-first order.
+// nodes of the files supplied to [New] in depth-first order.
 // It visits each node n before n's children.
 // The complete traversal sequence is determined by ast.Inspect.
 //
-// The types argument, if non-empty, enables type-based
-// filtering of events: only nodes whose type matches an
-// element of the types slice are included in the sequence.
+// The types argument, if non-empty, enables type-based filtering:
+// only nodes whose type matches an element of the types slice are
+// included in the sequence.
+//
+// Example:
+//
+//	for call := range in.PreorderSeq((*ast.CallExpr)(nil)) { ... }
+//
+// The [All] function is more convenient if there is exactly one node type:
+//
+//	for call := range All[*ast.CallExpr](in) { ... }
+//
+// See also the newer and more flexible [Cursor] API, which lets you
+// start the traversal at an arbitrary node, and reports each matching
+// node by its Cursor, enabling easier navigation.
+// The above example would be written thus:
+//
+//	for curCall := range in.Root().Preorder((*ast.CallExpr)(nil)) {
+//		call := curCall.Node().(*ast.CallExpr)
+//		...
+//	}
 func (in *Inspector) PreorderSeq(types ...ast.Node) iter.Seq[ast.Node] {
 
 	// This implementation is identical to Preorder,
@@ -53,6 +71,16 @@ func (in *Inspector) PreorderSeq(types ...ast.Node) iter.Seq[ast.Node] {
 // Example:
 //
 //	for call := range All[*ast.CallExpr](in) { ... }
+//
+// See also the newer and more flexible [Cursor] API, which lets you
+// start the traversal at an arbitrary node, and reports each matching
+// node by its Cursor, enabling easier navigation.
+// The above example would be written thus:
+//
+//	for curCall := range in.Root().Preorder((*ast.CallExpr)(nil)) {
+//		call := curCall.Node().(*ast.CallExpr)
+//		...
+//	}
 func All[N interface {
 	*S
 	ast.Node