Improve actor builder documentation

Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>

Author: didier-wenzek

crates/core/tedge_actors/src/builders.rs

@@ -47,17 +47,17 @@
 //!   (possibly several receivers to handle message priorities among inputs),
 //!   and has to give clones of the associated Sender (or Senders) to its peers.
 //! - The first responsibility of a builder is to create a channel per receiver of the actor
-//!   under construction. The receiver will be given to the actor on build.
+//!   under construction. The receiver will be given to the actor when built.
 //!   The sender is owned by the builder to be cloned and given to any peer that needs to send data
 //!   to the actor under construction.
-//! - The second responsibility of the builder is to collect a Sender for each peer the actor
+//! - The second responsibility of the builder is to collect a sender for each peer the actor
 //!   under construction needs to send messages to. This is the mirror of the previous responsibility:
 //!   each builder gives to the others clones of its senders and collects senders from others.
 //! - This is why all the actor building traits
 //!   ([MessageSource], [MessageSink] and [RuntimeRequestSink])
-//!   are related to exchanges of Sender. A sink gives to a source a sender attached to its receiver.
-//! - To be precise, the actor builders exchange [DynSender] and not [Sender]. The difference is that
-//!   a [DynSender] can transform the messages sent by the source to adapt them to the sink expectations,
+//!   are related to exchanges of Sender. A sink gives to a source a sender attached to its own receiver.
+//! - To be precise, the actor builders exchange [DynSender] and not [Sender](futures::channel::mpsc::Sender).
+//!   The difference is that a [DynSender] can transform the messages sent by the source to adapt them to the sink expectations,
 //!   using an `impl From<SourceMessage> for SinkMessage`. This flexibility allows an actor to receive
 //!   messages from several independent sources (see the [fan_in_message_type](crate::fan_in_message_type) macro).
 use crate::mpsc;

crates/core/tedge_actors/src/channels.rs

@@ -25,7 +25,7 @@ pub trait CloneSender<M>: Sender<M> {
 
     /// Clone a cast of this sender into a `Box<dyn Sender<M>>`
     ///
-    /// This is a workaround for https://github.com/rust-lang/rust/issues/65991
+    /// This is a workaround for <https://github.com/rust-lang/rust/issues/65991>
     fn sender(&self) -> Box<dyn Sender<M>>;
 }
 

crates/core/tedge_actors/src/lib.rs

@@ -4,7 +4,7 @@
 //!
 //! Actors are processing units that interact using asynchronous messages.
 //!
-//! The behavior of an [Actor](crate::Actor) is defined by:
+//! The behavior of an [Actor] is defined by:
 //! - a state owned and freely updated by the actor,
 //! - a [message box](crate::message_boxes) connected to peer actors,
 //! - input [messages](crate::Message) that the actor receives from its peers and processes in turn,
@@ -87,9 +87,9 @@
 //! ```
 //!
 //! This crate provides specific `Actor` implementations:
-//! - The [ServerActor](crate::ServerActor) wraps a [Server](crate::Server),
+//! - The [ServerActor] wraps a [Server],
 //!   to implement a request-response communication pattern with a set of connected client actors.
-//! - The [ConvertingActor](crate::ConvertingActor) wraps a [Converter](crate::Converter),
+//! - The [ConvertingActor] wraps a [Converter],
 //!   that translates each input message into a sequence of output messages.
 //!
 //! ## Testing an actor
@@ -104,9 +104,8 @@
 //! [Actor and message box builders](crate::builders) are provided to address these specificities
 //! with a generic approach without exposing the internal structure of the actors.
 //!
-//! To test the `Calculator` example we need first to create its box using a
-//! [SimpleMessageBoxBuilder](crate::SimpleMessageBoxBuilder),
-//! as this actor expects a [SimpleMessageBox](crate::SimpleMessageBox).
+//! To test the `Calculator` example we need first to create its box using a [SimpleMessageBoxBuilder],
+//! as this actor expects a [SimpleMessageBox].
 //! And then, to create a test box connected to the actor message box,
 //! we use the [ServiceProviderExt](crate::test_helpers::ServiceProviderExt) test helper extension
 //! and the [new_client_box](crate::test_helpers::ServiceProviderExt::new_client_box) method.
@@ -153,7 +152,7 @@
 //! # }
 //! ```
 //!
-//! See the [test_helpers](crate::test_helpers) module for various ways
+//! See the [test_helpers] module for various ways
 //! to observe and interact with running actors.
 //!
 //! - The primary tool to interact with an actor under test is the [SimpleMessageBoxBuilder],
@@ -172,26 +171,20 @@
 //! that define the services provided and consumed by the actors under construction.
 //!
 //! The connection builder traits work by pairs.
-//! A [MessageSink](crate::MessageSink) connects to a [MessageSource](crate::MessageSource),
+//! A [MessageSink] connects to a [MessageSource],
 //! so the messages sent by the latter will be received by the former.
 //!
 //! These traits define the types of the messages sent and received.
 //! - A sink that excepts message of type `M` can only be connected to a source of messages
 //!   that can be converted into `M` values.
-//! - Similarly a service is defined by two types of messages, the requests received by the service
-//!   and the responses sent by the service. To use a service, a consumer will have to send messages
-//!   that can be converted into the service request type and be ready to receive messages converted from
-//!   the service response type.
 //! - Note, that no contract is enforced beyond the type-compatibility of the messages sent between the actors.
 //!   A consumer of an HTTP service needs to known that a request must be sent before any response can be received;
 //!   while a consumer of an MQTT service can expect to receive messages without sending a single one.
 //!
 //! The connection builder traits also define a configuration type.
-//! - The semantics of this type is defined by the message source or the service provider.
-//!   It can be used to filter the values sent to a given sink
-//!   or to restrict the scope of the service provided to a given service consumer.
-//! - The configuration values are provided by the message sinks and the service consumers
-//!   to specify the context of their connection to a source or a service.
+//! - The semantics of this type is defined by the message source and is used to filter the values sent to a sink.
+//! - The actual configuration values are provided by the actor sinks when connecting the source
+//!   to specify the subset of messages their are interested into.
 //!
 //! Note that these traits are implemented by the actor builders, not by the actors themselves.
 //!

crates/core/tedge_actors/src/message_boxes.rs

@@ -7,11 +7,11 @@
 //! Conceptually, a message box is a receiver of input messages combined with a sender of output messages.
 //! * The receiver is connected to the senders of peer actors;
 //!   and reciprocally the sender is connected to receivers of peer actors.
-//! * The receivers are [mpsc::Receiver](crate::mpsc::Receiver) that collect messages from several sources,
+//! * The receivers are [mpsc::Receiver] that collect messages from several sources,
 //!   and deliver the messages to the actor in the order they have been received.
-//! * The senders are [DynSender](crate::DynSender) that adapt the messages sent to match constraints of the receivers.
+//! * The senders are [DynSender] that adapt the messages sent to match constraints of the receivers.
 //!
-//! A [SimpleMessageBox](crate::SimpleMessageBox) implements exactly this conceptual view:
+//! A [SimpleMessageBox] implements exactly this conceptual view:
 //!
 //! ```ascii
 //!                    input_senders: DynSender<Input> ...
@@ -79,7 +79,7 @@
 //!
 //! This crates provides several built-in message box implementations:
 //!
-//! - [SimpleMessageBox](crate::SimpleMessageBox) for actors that simply process messages in turn,
+//! - [SimpleMessageBox] for actors that simply process messages in turn,
 //! - [ServerMessageBox](crate::ServerMessageBox) for server actors that deliver a request-response service,
 //! - [ConcurrentServerMessageBox](crate::ConcurrentServerMessageBox) for server actors that process requests concurrently,
 //! - [ClientMessageBox](crate::ClientMessageBox) for client actors that use a request-response service from a server actor,

crates/core/tedge_actors/src/servers/message_boxes.rs

@@ -109,7 +109,7 @@ impl<Request: Message, Response: Message> Clone for ClientMessageBox<Request, Re
 }
 
 impl<Request: Message, Response: Message> ClientMessageBox<Request, Response> {
-    /// Create a [ClientMessageBox] connected to a given [Server]
+    /// Create a [ClientMessageBox] connected to a given [Server](crate::Server)
     pub fn new(server: &mut impl MessageSink<RequestEnvelope<Request, Response>>) -> Self {
         ClientMessageBox {
             sender: server.get_sender(),

crates/core/tedge_actors/src/servers/mod.rs

@@ -47,7 +47,7 @@
 //! }
 //! ```
 //!
-//! To be used as an actor, a `Server` is wrapped into a [ServerActor](crate::ServerActor)
+//! To be used as an actor, a `Server` is wrapped into a [ServerActor]
 //!
 //! ```
 //! # use tedge_actors::{Actor, Builder, NoConfig, MessageReceiver, Sender, ServerActorBuilder, ServerConfig, Sequential};

crates/core/tedge_actors/src/test_helpers.rs

@@ -399,7 +399,7 @@ use futures::StreamExt;
 /// The two actors under test, as well as their message boxes, are built and launched as usual,
 /// the only interaction being on the wire:
 /// - A probe is set on one side using the [with_probe()](crate::test_helpers::ServiceConsumerExt::with_probe)
-///   method added by the [ServiceConsumerExt](crate::test_helpers::ServiceConsumerExt)
+///   method added by the [ServiceConsumerExt]
 ///   to any actor or message box builder.
 /// - The [Probe::observe()](crate::test_helpers::Probe::observe) method can then be used
 ///   to observe all the messages either [sent](crate::test_helpers::ProbeEvent::Send)
@@ -459,7 +459,7 @@ pub struct Probe<I: MessagePlus, O: MessagePlus> {
     output_forwarder: DynSender<O>,
 }
 
-/// An event observed by a [Probe](crate::test_helpers::Probe)
+/// An event observed by a [Probe]
 ///
 /// These events have to be interpreted from the point of view of
 /// the actor on which the probe has been set.
@@ -491,8 +491,7 @@ impl<I: MessagePlus, O: MessagePlus> Probe<I, O> {
     /// Create a new `Probe` ready to be interposed between two actors.
     ///
     /// The connection is done using the [with_probe()](crate::test_helpers::ServiceConsumerExt::with_probe)
-    /// method added to any [ServiceConsumer](crate::ServiceConsumer)
-    /// by [ServiceConsumerExt](crate::test_helpers::ServiceConsumerExt).
+    /// method added by [ServiceConsumerExt] to any actor builder implementing [MessageSource] and [MessageSink].
     pub fn new() -> Self {
         // The capacity of the interceptor channels is 1,
         // so the probe will control at which pace input/output messages are sent.
@@ -598,15 +597,15 @@ impl<I: MessagePlus, O: MessagePlus> Probe<I, O> {
     }
 }
 
-/// Extend any [ServiceConsumer] with a `with_probe` method.
+/// Extend with a `with_probe` method any actor builder implementing [MessageSource] and [MessageSink].
 pub trait ServiceConsumerExt<Request: MessagePlus, Response: MessagePlus> {
-    /// Add a probe to an actor `self` that is a [MessageSource](crate::MessageSource) and [MessageSink](crate::MessageSink).
+    /// Add a probe to an actor `self` that is a [MessageSource] and [MessageSink].
     ///
-    /// Return a [MessageSource](crate::MessageSource) and [MessageSink](crate::MessageSink)
+    /// Return a [MessageSource] and [MessageSink]
     /// that can be plugged into another actor which consumes the source messages and produces messages for the sink.
     ///
     /// The added `Probe` is then interposed between the two actors,
-    /// observing all the [ProbeEvent](crate::test_helpers::ProbeEvent) exchanged between them.
+    /// observing all the [ProbeEvent] exchanged between them.
     ///
     /// ```
     /// # use tedge_actors::{NoConfig, ServerMessageBoxBuilder, SimpleMessageBoxBuilder};