Skip to content

Commit

Permalink
wasmparser: add and improve doc tests (#1913)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
Robbepop authored Nov 27, 2024
1 parent c0eab4d commit 4df1c11
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 5 deletions.
41 changes: 39 additions & 2 deletions crates/wasmparser/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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;
Expand Down
18 changes: 15 additions & 3 deletions crates/wasmparser/src/readers/core/operators.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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")]
Expand Down

0 comments on commit 4df1c11

Please sign in to comment.