Adapt names with documentation to be more fitting

Signed-off-by: Marcel Müller <m.mueller@ifm.com>

5 files changed, 66 insertions, 31 deletions

diff --git a/crates/core/tedge_api/examples/heartbeat.rs b/crates/core/tedge_api/examples/heartbeat.rs
index cb05b4b1..35ac183d 100644
--- a/crates/core/tedge_api/examples/heartbeat.rs
+++ b/crates/core/tedge_api/examples/heartbeat.rs
@@ -9,7 +9,7 @@ use futures::FutureExt;
 use tedge_api::{
     address::ReplySender,
     message::NoReply,
-    plugin::{BuiltPlugin, Handle, HandleTypes, Message, PluginDeclaration, PluginExt},
+    plugin::{BuiltPlugin, Handle, Message, PluginDeclaration, PluginExt},
     Address, CancellationToken, Plugin, PluginBuilder, PluginConfiguration, PluginDirectory,
     PluginError,
 };
@@ -45,7 +45,7 @@ impl<PD: PluginDirectory> PluginBuilder<PD> for HeartbeatServiceBuilder {
     where
         Self: Sized,
     {
-        HandleTypes::empty()
+        HeartbeatService::get_handled_types()
     }
 
     async fn verify_configuration(
@@ -79,7 +79,7 @@ impl<PD: PluginDirectory> PluginBuilder<PD> for HeartbeatServiceBuilder {
             monitored_services,
             cancellation_token,
         )
-        .into_untyped())
+        .finish())
     }
 }
 
@@ -109,7 +109,7 @@ impl Plugin for HeartbeatService {
     ///
     /// Because this example is _simple_, we do not spawn a background task that periodically sends
     /// the heartbeat. In a real world scenario, that background task would be started here.
-    async fn setup(&mut self) -> Result<(), PluginError> {
+    async fn start(&mut self) -> Result<(), PluginError> {
         println!(
             "HeartbeatService: Setting up heartbeat service with interval: {:?}!",
             self.interval_duration
@@ -230,7 +230,7 @@ impl<PD: PluginDirectory> PluginBuilder<PD> for CriticalServiceBuilder {
         Ok(CriticalService {
             status: tokio::sync::Mutex::new(true),
         }
-        .into_untyped())
+        .finish())
     }
 }
 
@@ -271,7 +271,7 @@ impl PluginDeclaration for CriticalService {
 /// Because the CriticalService is of course a Plugin, it needs an implementation for that as well.
 #[async_trait]
 impl Plugin for CriticalService {
-    async fn setup(&mut self) -> Result<(), PluginError> {
+    async fn start(&mut self) -> Result<(), PluginError> {
         println!("CriticalService: Setting up critical service!");
         Ok(())
     }
@@ -420,8 +420,8 @@ async fn main() {
     let mut heartbeat = build_heartbeat_plugin(&mut comms, cancel_token.child_token()).await;
     let mut critical_service = build_critical_plugin(&mut comms, cancel_token.child_token()).await;
 
-    heartbeat.plugin_mut().setup().await.unwrap();
-    critical_service.plugin_mut().setup().await.unwrap();
+    heartbeat.plugin_mut().start().await.unwrap();
+    critical_service.plugin_mut().start().await.unwrap();
 
     let mut recv = comms
         .plugins
diff --git a/crates/core/tedge_api/src/address.rs b/crates/core/tedge_api/src/address.rs
index 38fdfa8b..1e498199 100644
--- a/crates/core/tedge_api/src/address.rs
+++ b/crates/core/tedge_api/src/address.rs
@@ -157,9 +157,36 @@ pub trait ReceiverBundle: Send + 'static {
 #[doc(hidden)]
 pub trait Contains<M: Message> {}
 
-/// Declare a set of messages to be a "MessageBundle"
+/// Declare a set of messages to be a [`ReceiverBundle`] which is then used with an [`Address`] to
+/// specify which kind of messages a given recipient plugin has to support.
 ///
-/// This macro can be used by a plugin author to declare a set of messages to be a `MessageBundle`.
+/// The list of messages MUST be a subset of the messages the plugin behind `Address` supports.
+///
+/// ## Example
+///
+/// ```rust
+/// # use tedge_api::{Message, make_receiver_bundle, message::NoReply};
+///
+/// #[derive(Debug)]
+/// struct IntMessage(u8);
+///
+/// impl Message for IntMessage {
+///     type Reply = NoReply;
+/// }
+///
+/// #[derive(Debug)]
+/// struct StatusMessage(String);
+///
+/// impl Message for StatusMessage {
+///     type Reply = NoReply;
+/// }
+///
+/// make_receiver_bundle!(struct MessageReceiver(IntMessage, StatusMessage));
+///
+/// // or if you want to export it
+///
+/// make_receiver_bundle!(pub struct AnotherMessageReceiver(IntMessage, StatusMessage));
+/// ```
 #[macro_export]
 macro_rules! make_receiver_bundle {
     ($pu:vis struct $name:ident($($msg:ty),+)) => {
diff --git a/crates/core/tedge_api/src/lib.rs b/crates/core/tedge_api/src/lib.rs
index 477bc779..3ebb4a20 100644
--- a/crates/core/tedge_api/src/lib.rs
+++ b/crates/core/tedge_api/src/lib.rs
@@ -11,7 +11,7 @@
 
 /// All the parts required to write a plugin
 pub mod plugin;
-pub use plugin::{Plugin, PluginBuilder, PluginConfiguration, PluginDirectory, PluginExt};
+pub use plugin::{Message, Plugin, PluginBuilder, PluginConfiguration, PluginDirectory, PluginExt};
 
 /// Addresses allow plugins to exchange messages
 pub mod address;
diff --git a/crates/core/tedge_api/src/message.rs b/crates/core/tedge_api/src/message.rs
index 5b980d7b..decb41e5 100644
--- a/crates/core/tedge_api/src/message.rs
+++ b/crates/core/tedge_api/src/message.rs
@@ -1,7 +1,7 @@
 use crate::plugin::Message;
 
 #[derive(Debug)]
-/// A message which cannot be constructed and thus cannot be used to reply with
+/// A message which cannot be constructed and thus can be used when no reply is expected.
 pub enum NoReply {}
 
 impl Message for NoReply {
diff --git a/crates/core/tedge_api/src/plugin.rs b/crates/core/tedge_api/src/plugin.rs
index 96c630be..b538d7fc 100644
--- a/crates/core/tedge_api/src/plugin.rs
+++ b/crates/core/tedge_api/src/plugin.rs
@@ -40,7 +40,7 @@ pub trait PluginDirectory: Send + Sync {
     ///
     /// ## Also see
     ///
-    /// - [`make_message_bundle`] On how to define your own named message bundle
+    /// - [`make_receiver_bundle`](crate::make_receiver_bundle) On how to define your own named message bundle
     fn get_address_for<RB: ReceiverBundle>(
         &self,
         name: &str,
@@ -91,7 +91,8 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static {
     /// This function must return a `HandleTypes` object which represents the types of messages
     /// that a plugin is able to handle.
     ///
-    /// To create an instance of this type, you must use the [`HandleTypes::get_handlers_for`] method.
+    /// To create an instance of this type, you must call the [`PluginExt::get_handled_types`]
+    /// method on the plugin this PluginBuilder will build
     ///
     /// # Example
     ///
@@ -108,7 +109,7 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static {
     /// struct MyPlugin; // + some impl Plugin for MyPlugin
     /// # #[async_trait::async_trait]
     /// # impl Plugin for MyPlugin {
-    /// #     async fn setup(&mut self) -> Result<(), PluginError> {
+    /// #     async fn start(&mut self) -> Result<(), PluginError> {
     /// #         unimplemented!()
     /// #     }
     /// #     async fn shutdown(&mut self) -> Result<(), PluginError> {
@@ -192,7 +193,7 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static {
     ///
     /// This function is called by the core of thin-edge to create a new plugin instance.
     ///
-    /// The `PluginExt::into_untyped()` function can be used to make any `Plugin` implementing type
+    /// The [`PluginExt::finish()`] function can be used to make any type implementing [`Plugin`]
     /// into a `BuiltPlugin`, which the function requires to be returned (see example below).
     ///
     /// # Note
@@ -220,7 +221,7 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static {
     /// struct MyPlugin; // + some impl Plugin for MyPlugin
     /// # #[async_trait::async_trait]
     /// # impl Plugin for MyPlugin {
-    /// #     async fn setup(&mut self) -> Result<(), tedge_api::error::PluginError> {
+    /// #     async fn start(&mut self) -> Result<(), tedge_api::error::PluginError> {
     /// #         unimplemented!()
     /// #     }
     /// #     async fn shutdown(&mut self) -> Result<(), tedge_api::error::PluginError> {
@@ -257,7 +258,7 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static {
     ///     {
     ///         use tedge_api::plugin::PluginExt;
     ///         let p = MyPlugin {};
-    ///         Ok(p.into_untyped())
+    ///         Ok(p.finish())
     ///     }
     ///     // other trait functions...
     /// #   fn kind_name() -> &'static str {
@@ -293,14 +294,14 @@ pub trait PluginBuilder<PD: PluginDirectory>: Sync + Send + 'static {
 /// If a plugin also would like to receive messages, the author of a plugin must also implement the
 /// `Handle` trait.
 ///
-/// The functionality implemented via the `Plugin` trait is used to setup the plugin before
+/// The functionality implemented via the `Plugin` trait is used to start the plugin before
 /// messages are sent to it, and to shut the plugin down when thin-edge stops operation.
 ///
-/// The `Plugin::setup` function would be the place where a plugin author would create background
+/// The [`Plugin::start`] function would be the place where a plugin author would create background
 /// tasks, if their plugin must send messages pro-actively.
 #[async_trait]
 pub trait Plugin: Sync + Send + DowncastSync {
-    /// The plugin can set itself up here
+    /// The plugin can start itself here
     ///
     /// This function will be called by the core of thin-edge before any message-passing starts.
     /// The plugin is free to for example spawn up background tasks here.
@@ -377,7 +378,7 @@ impl HandleTypes {
     /// # use tedge_api::{Address, CoreMessages, error::DirectoryError, address::ReceiverBundle};
     /// # #[async_trait::async_trait]
     /// # impl tedge_api::Plugin for HeartbeatPlugin {
-    /// #     async fn setup(&mut self) -> Result<(), PluginError> {
+    /// #     async fn start(&mut self) -> Result<(), PluginError> {
     /// #         unimplemented!()
     /// #     }
     /// #
@@ -409,12 +410,6 @@ impl HandleTypes {
     {
         HandleTypes(P::HandledMessages::get_ids())
     }
-
-    /// Empty list of types. A plugin that does not handle anything will not be able to receive
-    /// messages except through replies sent with [`Reply`](crate::address::Reply)
-    pub fn empty() -> HandleTypes {
-        HandleTypes(Vec::with_capacity(0))
-    }
 }
 
 impl From<HandleTypes> for HashSet<(&'static str, TypeId)> {
@@ -427,6 +422,11 @@ impl From<HandleTypes> for HashSet<(&'static str, TypeId)> {
 ///
 /// This trait is a marker trait for all types that can be used as messages which can be send
 /// between plugins in thin-edge.
+///
+/// ## Note
+///
+/// A message without the expectation of a reply can use the [`NoReply`](crate::message::NoReply)
+/// type.
 pub trait Message: 'static + Send + std::fmt::Debug {
     type Reply: Message;
 }
@@ -447,15 +447,20 @@ pub trait MessageBundle {
 pub trait PluginExt: PluginDeclaration {
     /// Convert a `Plugin` into a `BuiltPlugin`
     ///
-    /// This function is only available if the Plugin is able to handle messages that are inside
-    /// the specified `MessageBundle`.
-    fn into_untyped(self) -> BuiltPlugin
+    /// This is used in the [`PluginBuilder::instantiate`] method to convert a struct implementing
+    /// `Plugin + PluginDeclaration` to a generic struct that the core of ThinEdge can then handle.
+    ///
+    /// This function is only available if the Plugin is able to handle messages that are specified
+    /// in [`PluginDeclaration::HandledMessages`].
+    fn finish(self) -> BuiltPlugin
     where
         Self: DoesHandle<Self::HandledMessages> + Sized,
     {
         self.into_built_plugin()
     }
 
+    /// Get the list of types that are handled by this [`Plugin`] as specified in the
+    /// [`PluginDeclaration`]
     fn get_handled_types() -> HandleTypes
     where
         Self: DoesHandle<Self::HandledMessages> + Sized,
@@ -479,6 +484,8 @@ pub struct BuiltPlugin {
 }
 
 impl BuiltPlugin {
+    /// THIS IS PART OF THE PRIVATE API DO NOT USE
+    #[doc(hidden)]
     pub fn new(plugin: Box<dyn Plugin>, handler: PluginHandlerFn) -> Self {
         Self { plugin, handler }
     }
@@ -507,6 +514,7 @@ impl BuiltPlugin {
     }
 }
 
+/// THIS IS PART OF THE PRIVATE API DO NOT USE
 #[doc(hidden)]
 pub trait DoesHandle<M: MessageBundle> {
     fn into_built_plugin(self) -> BuiltPlugin;