fluencelabs/rust-libp2p
1
0
Fork 0
mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-06-25 15:51:34 +00:00
Code Issues Projects Releases Wiki Activity

Enhance NetworkBehaviour docs (#1362)

Browse Source 
* add docs about deriving NetworkBehaviour

* add commentary to the chat example

also minor stuff like reordering to match the struct elements, note why the listening address is
reported in poll.

* fix remove the warning on the example ignored field

* Apply suggestions from code review

Thanks for suggestions!

Co-Authored-By: Max Inden <mail@max-inden.de>

* chore cleanup added docs after suggestions

* fix print all listening addresses in examples/chat

not that there should be more than one but it makes sense to repeat the full example here.

* chore remove confusing writing on printing the listening addrs

* fix use intra-docs, spelling

Co-Authored-By: Roman S. Borschel <roman@parity.io>

Co-authored-by: Max Inden <mail@max-inden.de>
Co-authored-by: Roman Borschel <romanb@users.noreply.github.com>
This commit is contained in:
Joonas Koivunen
2020-01-14 13:48:16 +02:00
committed by Roman Borschel
parent 3f968cbf92
commit 7df3e74d79
3 changed files with 42 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
swarm/src/behaviour.rs
View File

@ -26,6 +26,23 @@ use std::{error, task::Context, task::Poll};
///
/// This trait has been designed to be composable. Multiple implementations can be combined into
/// one that handles all the behaviours at once.
///
/// # Deriving `NetworkBehaviour`
///
/// 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. Any events
/// generated by struct members are delegated to [`NetworkBehaviourEventProcess`] implementations
/// which are expected to be provided by the user.
///
/// Optionally one can implement a custom `poll` function, which needs to be tagged with the
/// `#[behaviour(poll_method = "poll")]` attribute, and would be called last with no parameters.
///
/// By default the derive sets the `NetworkBehaviour::OutEvent` as `()` but this can be overriden
/// with `#[behaviour(out_event = "AnotherType")]`.
///
/// `#[behaviour(ignore)]` can be added on a struct field to disable generation of delegation to
/// the fields which do not implement `NetworkBehaviour`.
pub trait NetworkBehaviour {
/// Handler for all the protocols the network behaviour supports.
type ProtocolsHandler: IntoProtocolsHandler;
@ -163,9 +180,8 @@ pub trait PollParameters {
fn local_peer_id(&self) -> &PeerId;
}
/// Used when deriving `NetworkBehaviour`. When deriving `NetworkBehaviour`, must be implemented
/// for all the possible event types generated by the various fields.
// TODO: document how the custom behaviour works and link this here
/// When deriving [`NetworkBehaviour`] this trait must be implemented for all the possible event types
/// generated by the inner behaviours.
pub trait NetworkBehaviourEventProcess<TEvent> {
/// Called when one of the fields of the type you're deriving `NetworkBehaviour` on generates
/// an event.