From 4df1c118d09484c3b72cfdf1d8fa26d9034751c1 Mon Sep 17 00:00:00 2001
From: Robin Freyler <robin.freyler@gmail.com>
Date: Wed, 27 Nov 2024 17:14:08 +0100
Subject: [PATCH] `wasmparser`: add and improve doc tests (#1913)

* fix docs for `for_each_visit_operator` macro

* add doc example to `for_each_visit_simd_operator` macro

* make simd_visitor doc test compile

* apply rustfmt
---
 crates/wasmparser/src/lib.rs                  | 41 ++++++++++++++++++-
 .../wasmparser/src/readers/core/operators.rs  | 18 ++++++--
 2 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/crates/wasmparser/src/lib.rs b/crates/wasmparser/src/lib.rs
index 7a7d8b027c..21c377536c 100644
--- a/crates/wasmparser/src/lib.rs
+++ b/crates/wasmparser/src/lib.rs
@@ -1130,8 +1130,8 @@ pub use _for_each_operator_impl as for_each_operator;
 ///     //
 ///     // The `$proposal` identifier indicates the Wasm proposals from which
 ///     // the Wasm operator is originating.
-///     // For example to specialize the macro match arm for Wasm SIMD proposal
-///     // operators you could write `@simd` instead of `@$proposal:ident` to
+///     // For example to specialize the macro match arm for Wasm `gc` proposal
+///     // operators you could write `@gc` instead of `@$proposal:ident` to
 ///     // only catch those operators.
 ///     //
 ///     // The `$op` name is bound to the `Operator` variant name. The
@@ -1233,6 +1233,43 @@ pub use _for_each_visit_operator_impl as for_each_visit_operator;
 /// https://github.com/WebAssembly/relaxed-simd
 ///
 /// [`VisitSimdOperator`]: crate::VisitSimdOperator
+///
+/// ```
+/// # macro_rules! define_visit_operator {
+/// #     ($( @$proposal:ident $op:ident $({ $($arg:ident: $argty:ty),* })? => $visit:ident ($($ann:tt)*))*) => {
+/// #         $( fn $visit(&mut self $($(,$arg: $argty)*)?) {} )*
+/// #     }
+/// # }
+/// pub struct VisitAndDoNothing;
+///
+/// impl<'a> wasmparser::VisitOperator<'a> for VisitAndDoNothing {
+///     type Output = ();
+///
+///     // implement all the visit methods ..
+///     # wasmparser::for_each_visit_operator!(define_visit_operator);
+/// }
+///
+/// macro_rules! define_visit_simd_operator {
+///     // The outer layer of repetition represents how all operators are
+///     // provided to the macro at the same time.
+///     //
+///     // The `$proposal` identifier is either `@simd` or `@relaxed_simd`.
+///     //
+///     // The shape of this macro is identical to [`for_each_visit_operator`].
+///     // Please refer to its documentation if you want to learn more.
+///     ($( @$proposal:ident $op:ident $({ $($arg:ident: $argty:ty),* })? => $visit:ident ($($ann:tt)*))*) => {
+///         $(
+///             fn $visit(&mut self $($(,$arg: $argty)*)?) {
+///                 // do nothing for this example
+///             }
+///         )*
+///     }
+/// }
+///
+/// impl<'a> wasmparser::VisitSimdOperator<'a> for VisitAndDoNothing {
+///     wasmparser::for_each_visit_simd_operator!(define_visit_simd_operator);
+/// }
+/// ```
 #[cfg(feature = "simd")]
 #[doc(inline)]
 pub use _for_each_visit_simd_operator_impl as for_each_visit_simd_operator;
diff --git a/crates/wasmparser/src/readers/core/operators.rs b/crates/wasmparser/src/readers/core/operators.rs
index 80e71d3e5c..84c8ff840c 100644
--- a/crates/wasmparser/src/readers/core/operators.rs
+++ b/crates/wasmparser/src/readers/core/operators.rs
@@ -440,17 +440,29 @@ pub trait VisitOperator<'a> {
     ///
     /// # Example
     ///
-    /// ```compile_fail
-    /// impl VisitOperator for MyVisitor {
+    /// ```
+    /// # macro_rules! define_visit_operator {
+    /// #     ($( @$proposal:ident $op:ident $({ $($arg:ident: $argty:ty),* })? => $visit:ident ($($ann:tt)*))*) => {
+    /// #         $( fn $visit(&mut self $($(,$arg: $argty)*)?) {} )*
+    /// #     }
+    /// # }
+    /// # use wasmparser::{VisitOperator, VisitSimdOperator};
+    /// pub struct MyVisitor;
+    ///
+    /// impl<'a> VisitOperator<'a> for MyVisitor {
+    ///     type Output = ();
+    ///
     ///     fn simd_visitor(&mut self) -> Option<&mut dyn VisitSimdOperator<'a, Output = Self::Output>> {
     ///         Some(self)
     ///     }
     ///
     ///     // implement remaining visitation methods here ...
+    ///     # wasmparser::for_each_visit_operator!(define_visit_operator);
     /// }
     ///
-    /// impl VisitSimdOperator for MyVisitor {
+    /// impl VisitSimdOperator<'_> for MyVisitor {
     ///     // implement SIMD visitation methods here ...
+    ///     # wasmparser::for_each_visit_simd_operator!(define_visit_operator);
     /// }
     /// ```
     #[cfg(feature = "simd")]