Documentation of the syntax tree traversals
diff --git a/codegen/src/main.rs b/codegen/src/main.rs
index 5ce71ae..ac674a0 100644
--- a/codegen/src/main.rs
+++ b/codegen/src/main.rs
@@ -1006,9 +1006,6 @@
"\
// THIS FILE IS AUTOMATICALLY GENERATED; DO NOT EDIT
-//! A Fold represents an AST->AST fold; it accepts an AST piece,
-//! and returns a piece of the same type.
-
#![cfg_attr(rustfmt, rustfmt_skip)]
// Unreachable code is generated sometimes without the full feature.
@@ -1024,18 +1021,11 @@
{full_macro}
-/// AST->AST fold.
+/// Syntax tree traversal to transform the nodes of an owned syntax tree.
///
-/// Each method of the Fold trait is a hook to be potentially overridden. Each
-/// method's default implementation recursively visits the substructure of the
-/// input via the `walk` functions, which perform an \"identity fold\", that
-/// is, they return the same structure that they are given (for example the
-/// `fold_file` method by default calls `fold::walk_file`).
+/// See the [module documentation] for details.
///
-/// If you want to ensure that your code handles every variant
-/// explicitly, you need to override each method. (And you also need
-/// to monitor future changes to `Fold` in case a new method with a
-/// new default implementation gets introduced.)
+/// [module documentation]: index.html
pub trait Fold {{
{fold_trait}
}}
@@ -1078,11 +1068,6 @@
"\
// THIS FILE IS AUTOMATICALLY GENERATED; DO NOT EDIT
-//! AST walker. Each overridden visit method has full control over what
-//! happens with its node, it can do its own traversal of the node's children,
-//! call `visit::walk_*` to apply the default traversal algorithm, or prevent
-//! deeper traversal by doing nothing.
-
#![cfg_attr(rustfmt, rustfmt_skip)]
#![cfg_attr(feature = \"cargo-clippy\", allow(match_same_arms))]
@@ -1096,15 +1081,11 @@
{full_macro}
-/// Each method of the Visit trait is a hook to be potentially
-/// overridden. Each method's default implementation recursively visits
-/// the substructure of the input via the corresponding `walk` method;
-/// e.g. the `visit_mod` method by default calls `visit::walk_mod`.
+/// Syntax tree traversal to walk a shared borrow of a syntax tree.
///
-/// If you want to ensure that your code handles every variant
-/// explicitly, you need to override each method. (And you also need
-/// to monitor future changes to `Visit` in case a new method with a
-/// new default implementation gets introduced.)
+/// See the [module documentation] for details.
+///
+/// [module documentation]: index.html
pub trait Visit<'ast> {{
{visit_trait}
}}
@@ -1122,11 +1103,6 @@
"\
// THIS FILE IS AUTOMATICALLY GENERATED; DO NOT EDIT
-//! AST walker. Each overridden visit method has full control over what
-//! happens with its node, it can do its own traversal of the node's children,
-//! call `visit::walk_*` to apply the default traversal algorithm, or prevent
-//! deeper traversal by doing nothing.
-
#![cfg_attr(rustfmt, rustfmt_skip)]
#![cfg_attr(feature = \"cargo-clippy\", allow(match_same_arms))]
@@ -1140,15 +1116,12 @@
{full_macro}
-/// Each method of the VisitMut trait is a hook to be potentially
-/// overridden. Each method's default implementation recursively visits
-/// the substructure of the input via the corresponding `walk` method;
-/// e.g. the `visit_mod` method by default calls `visit::walk_mod`.
+/// Syntax tree traversal to mutate an exclusive borrow of a syntax tree in
+/// place.
///
-/// If you want to ensure that your code handles every variant
-/// explicitly, you need to override each method. (And you also need
-/// to monitor future changes to `VisitMut` in case a new method with a
-/// new default implementation gets introduced.)
+/// See the [module documentation] for details.
+///
+/// [module documentation]: index.html
pub trait VisitMut {{
{visit_mut_trait}
}}
diff --git a/src/gen/fold.rs b/src/gen/fold.rs
index 0794f69..190e3b6 100644
--- a/src/gen/fold.rs
+++ b/src/gen/fold.rs
@@ -1,8 +1,5 @@
// THIS FILE IS AUTOMATICALLY GENERATED; DO NOT EDIT
-//! A Fold represents an AST->AST fold; it accepts an AST piece,
-//! and returns a piece of the same type.
-
#![cfg_attr(rustfmt, rustfmt_skip)]
// Unreachable code is generated sometimes without the full feature.
@@ -28,18 +25,11 @@
}
-/// AST->AST fold.
+/// Syntax tree traversal to transform the nodes of an owned syntax tree.
///
-/// Each method of the Fold trait is a hook to be potentially overridden. Each
-/// method's default implementation recursively visits the substructure of the
-/// input via the `walk` functions, which perform an "identity fold", that
-/// is, they return the same structure that they are given (for example the
-/// `fold_file` method by default calls `fold::walk_file`).
+/// See the [module documentation] for details.
///
-/// If you want to ensure that your code handles every variant
-/// explicitly, you need to override each method. (And you also need
-/// to monitor future changes to `Fold` in case a new method with a
-/// new default implementation gets introduced.)
+/// [module documentation]: index.html
pub trait Fold {
# [ cfg ( any ( feature = "full" , feature = "derive" ) ) ]
fn fold_abi(&mut self, i: Abi) -> Abi { fold_abi(self, i) }
diff --git a/src/gen/visit.rs b/src/gen/visit.rs
index 8b6c004..5f0cb02 100644
--- a/src/gen/visit.rs
+++ b/src/gen/visit.rs
@@ -1,10 +1,5 @@
// THIS FILE IS AUTOMATICALLY GENERATED; DO NOT EDIT
-//! AST walker. Each overridden visit method has full control over what
-//! happens with its node, it can do its own traversal of the node's children,
-//! call `visit::walk_*` to apply the default traversal algorithm, or prevent
-//! deeper traversal by doing nothing.
-
#![cfg_attr(rustfmt, rustfmt_skip)]
#![cfg_attr(feature = "cargo-clippy", allow(match_same_arms))]
@@ -28,15 +23,11 @@
}
-/// Each method of the Visit trait is a hook to be potentially
-/// overridden. Each method's default implementation recursively visits
-/// the substructure of the input via the corresponding `walk` method;
-/// e.g. the `visit_mod` method by default calls `visit::walk_mod`.
+/// Syntax tree traversal to walk a shared borrow of a syntax tree.
///
-/// If you want to ensure that your code handles every variant
-/// explicitly, you need to override each method. (And you also need
-/// to monitor future changes to `Visit` in case a new method with a
-/// new default implementation gets introduced.)
+/// See the [module documentation] for details.
+///
+/// [module documentation]: index.html
pub trait Visit<'ast> {
# [ cfg ( any ( feature = "full" , feature = "derive" ) ) ]
fn visit_abi(&mut self, i: &'ast Abi) { visit_abi(self, i) }
diff --git a/src/gen/visit_mut.rs b/src/gen/visit_mut.rs
index 2408af0..96f3338 100644
--- a/src/gen/visit_mut.rs
+++ b/src/gen/visit_mut.rs
@@ -1,10 +1,5 @@
// THIS FILE IS AUTOMATICALLY GENERATED; DO NOT EDIT
-//! AST walker. Each overridden visit method has full control over what
-//! happens with its node, it can do its own traversal of the node's children,
-//! call `visit::walk_*` to apply the default traversal algorithm, or prevent
-//! deeper traversal by doing nothing.
-
#![cfg_attr(rustfmt, rustfmt_skip)]
#![cfg_attr(feature = "cargo-clippy", allow(match_same_arms))]
@@ -28,15 +23,12 @@
}
-/// Each method of the VisitMut trait is a hook to be potentially
-/// overridden. Each method's default implementation recursively visits
-/// the substructure of the input via the corresponding `walk` method;
-/// e.g. the `visit_mod` method by default calls `visit::walk_mod`.
+/// Syntax tree traversal to mutate an exclusive borrow of a syntax tree in
+/// place.
///
-/// If you want to ensure that your code handles every variant
-/// explicitly, you need to override each method. (And you also need
-/// to monitor future changes to `VisitMut` in case a new method with a
-/// new default implementation gets introduced.)
+/// See the [module documentation] for details.
+///
+/// [module documentation]: index.html
pub trait VisitMut {
# [ cfg ( any ( feature = "full" , feature = "derive" ) ) ]
fn visit_abi_mut(&mut self, i: &mut Abi) { visit_abi_mut(self, i) }
diff --git a/src/lib.rs b/src/lib.rs
index 8f6488e..cf2b2fe 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -388,12 +388,107 @@
pub mod spanned;
mod gen {
+ /// Syntax tree traversal to walk a shared borrow of a syntax tree.
+ ///
+ /// Each method of the [`Visit`] trait is a hook that can be overridden to
+ /// customize the behavior when visiting the corresponding type of node. By
+ /// default, every method recursively visits the substructure of the input
+ /// by invoking the right visitor method of each of its fields.
+ ///
+ /// [`Visit`]: trait.Visit.html
+ ///
+ /// ```rust
+ /// # use syn::{Attribute, BinOp, Expr, ExprBinary};
+ /// #
+ /// pub trait Visit<'ast> {
+ /// /* ... */
+ ///
+ /// fn visit_expr_binary(&mut self, node: &'ast ExprBinary) {
+ /// for attr in &node.attrs {
+ /// self.visit_attribute(attr);
+ /// }
+ /// self.visit_expr(&*node.left);
+ /// self.visit_bin_op(&node.op);
+ /// self.visit_expr(&*node.right);
+ /// }
+ ///
+ /// /* ... */
+ /// # fn visit_attribute(&mut self, node: &'ast Attribute);
+ /// # fn visit_expr(&mut self, node: &'ast Expr);
+ /// # fn visit_bin_op(&mut self, node: &'ast BinOp);
+ /// }
+ /// ```
#[cfg(feature = "visit")]
pub mod visit;
+
+ /// Syntax tree traversal to mutate an exclusive borrow of a syntax tree in
+ /// place.
+ ///
+ /// Each method of the [`VisitMut`] trait is a hook that can be overridden
+ /// to customize the behavior when mutating the corresponding type of node.
+ /// By default, every method recursively visits the substructure of the
+ /// input by invoking the right visitor method of each of its fields.
+ ///
+ /// [`VisitMut`]: trait.VisitMut.html
+ ///
+ /// ```rust
+ /// # use syn::{Attribute, BinOp, Expr, ExprBinary};
+ /// #
+ /// pub trait VisitMut {
+ /// /* ... */
+ ///
+ /// fn visit_expr_binary_mut(&mut self, node: &mut ExprBinary) {
+ /// for attr in &mut node.attrs {
+ /// self.visit_attribute_mut(attr);
+ /// }
+ /// self.visit_expr_mut(&mut *node.left);
+ /// self.visit_bin_op_mut(&mut node.op);
+ /// self.visit_expr_mut(&mut *node.right);
+ /// }
+ ///
+ /// /* ... */
+ /// # fn visit_attribute_mut(&mut self, node: &mut Attribute);
+ /// # fn visit_expr_mut(&mut self, node: &mut Expr);
+ /// # fn visit_bin_op_mut(&mut self, node: &mut BinOp);
+ /// }
+ /// ```
#[cfg(feature = "visit-mut")]
pub mod visit_mut;
+ /// Syntax tree traversal to transform the nodes of an owned syntax tree.
+ ///
+ /// Each method of the [`Fold`] trait is a hook that can be overridden to
+ /// customize the behavior when transforming the corresponding type of node.
+ /// By default, every method recursively visits the substructure of the
+ /// input by invoking the right visitor method of each of its fields.
+ ///
+ /// [`Fold`]: trait.Fold.html
+ ///
+ /// ```rust
+ /// # use syn::{Attribute, BinOp, Expr, ExprBinary};
+ /// #
+ /// pub trait Fold {
+ /// /* ... */
+ ///
+ /// fn fold_expr_binary(&mut self, node: ExprBinary) -> ExprBinary {
+ /// ExprBinary {
+ /// attrs: node.attrs
+ /// .into_iter()
+ /// .map(|attr| self.fold_attribute(attr))
+ /// .collect(),
+ /// left: Box::new(self.fold_expr(*node.left)),
+ /// op: self.fold_bin_op(node.op),
+ /// right: Box::new(self.fold_expr(*node.right)),
+ /// }
+ /// }
+ ///
+ /// /* ... */
+ /// # fn fold_attribute(&mut self, node: Attribute) -> Attribute;
+ /// # fn fold_expr(&mut self, node: Expr) -> Expr;
+ /// # fn fold_bin_op(&mut self, node: BinOp) -> BinOp;
+ /// }
+ /// ```
#[cfg(feature = "fold")]
pub mod fold;