From d9a76e7ec450b501d204ae87a22858a50af1e5f4 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Fri, 29 Oct 2021 19:33:51 +0200 Subject: [PATCH] swarm/src/behaviour: Fix outdated comment on derive's out_event The default behaviour changed with https://github.com/libp2p/rust-libp2p/pull/2214. This updates the doc comment. Initially raised in https://github.com/libp2p/rust-libp2p/pull/2290#issuecomment-944415562. --- swarm/src/behaviour.rs | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/swarm/src/behaviour.rs b/swarm/src/behaviour.rs index a8217eda066..1f3983b1bf8 100644 --- a/swarm/src/behaviour.rs +++ b/swarm/src/behaviour.rs @@ -39,27 +39,23 @@ type THandlerInEvent = /// /// Crate users can implement this trait by using the the `#[derive(NetworkBehaviour)]` /// proc macro re-exported by the `libp2p` crate. The macro generates a delegating `trait` -/// implementation for the `struct`, which delegates method calls to all trait members. +/// implementation for the `struct`, which delegates method calls to all struct members. +/// +/// Struct members that don't implement [`NetworkBehaviour`] must be annotated with `#[behaviour(ignore)]`. /// /// By default the derive sets the [`NetworkBehaviour::OutEvent`] as `()` but this can be overridden /// with `#[behaviour(out_event = "AnotherType")]`. /// -/// Struct members that don't implement [`NetworkBehaviour`] must be annotated with `#[behaviour(ignore)]`. -/// -/// By default, events generated by the remaining members are delegated to [`NetworkBehaviourEventProcess`] -/// implementations. Those must be provided by the user on the type that [`NetworkBehaviour`] is -/// derived on. +/// When setting a custom `out_event` users have to implement [`From`] converting from each of the +/// event types generated by the struct members to the custom `out_event`. /// -/// Alternatively, users can specify `#[behaviour(event_process = false)]`. In this case, users -/// should provide a custom `out_event` and implement [`From`] for each of the event types generated -/// by the struct members. -/// Not processing events within the derived [`NetworkBehaviour`] will cause them to be emitted as -/// part of polling the swarm in [`SwarmEvent::Behaviour`](crate::SwarmEvent::Behaviour). +/// Alternatively, users can specify `#[behaviour(event_process = true)]`. Events generated by the +/// struct members are delegated to [`NetworkBehaviourEventProcess`] implementations. Those must be +/// provided by the user on the type that [`NetworkBehaviour`] is derived on. /// -/// Optionally one can provide a custom `poll` function through the `#[behaviour(poll_method = "poll")]` -/// attribute. -/// This function must have the same signature as the [`NetworkBehaviour#poll`] function and will -/// be called last within the generated [`NetworkBehaviour`] implementation. +/// Optionally one can provide a custom `poll` function through the `#[behaviour(poll_method = +/// "poll")]` attribute. This function must have the same signature as the [`NetworkBehaviour#poll`] +/// function and will be called last within the generated [`NetworkBehaviour`] implementation. pub trait NetworkBehaviour: Send + 'static { /// Handler for all the protocols the network behaviour supports. type ProtocolsHandler: IntoProtocolsHandler;