update a lot of documentation

Author: schaze

README.md

@@ -7,6 +7,8 @@ The library provides fully typed support for all homie5 datatypes.
 
 Due to this, the usage of the library is a bit more involved as with a completly ready to use homie library. Benefit is however that you can use the library basically everywhere from a simple esp32, raspberrypi to a x86 machine.
 
+[![works with MQTT Homie](https://homieiot.github.io/img/works-with-homie.png)](https://homieiot.github.io/)
+
 ## Content
 
 <!-- TOC start (generated with https://github.com/derlin/bitdowntoc) -->

src/controller_proto.rs

@@ -1,3 +1,21 @@
+//! Provides MQTT subscription and publish message generators for a Homie 5 controller.
+//!
+//! This module implements the `Homie5ControllerProtocol` which generates MQTT messages necessary for discovering and controlling Homie 5 devices.
+//! The protocol manages the lifecycle of device discovery, subscribing to device attributes, and handling property changes.
+//!
+//! # Device Discovery Flow
+//! 1. Start with the Subscriptions returned by [`Homie5ControllerProtocol::discover_devices`]
+//!    This will subscribe to the $state attribute of all devices.
+//! 2. When receiving a [`Homie5Message::DeviceState`] message, check if the device is already
+//!    known, if not subscribe to the device using [`Homie5ControllerProtocol::subscribe_device`].
+//!    This will subscibe to all the other device attributes like $log/$description/$alert
+//! 3. When receiving a [`Homie5Message::DeviceDescription`] message, store the description for the
+//!    device and subscibe to all the property values using
+//!    [`Homie5ControllerProtocol::subscribe_props`]
+//! 4. after this you will start receiving [`Homie5Message::PropertyValue`] and
+//!    ['Homie5Message::PropertyTarget`] messages for the properties of the device
+//!
+
 use std::iter;
 
 use crate::{
@@ -7,38 +25,66 @@ use crate::{
     DEVICE_ATTRIBUTE_STATE, HOMIE_TOPIC_BROADCAST, HOMIE_VERSION, PROPERTY_ATTRIBUTE_TARGET, PROPERTY_SET_TOPIC,
 };
 
-/// Provides generators for all mqtt subscribe and publish packages needed for a homie5 controller
-/// ### The general order for discovering devices is as follows:
-/// * Start with the Subscriptions returned by [`Homie5ControllerProtocol::discover_devices`]
-///   This will subscribe to the $state attribute of all devices.
-/// * When receiving a [`Homie5Message::DeviceState`] message, check if the device is already
-///   known, if not subscribe to the device using [`Homie5ControllerProtocol::subscribe_device`].
-///   This will subscibe to all the other device attributes like $log/$description/$alert
-/// * When receiving a [`Homie5Message::DeviceDescription`] message, store the description for the
-///   device and subscibe to all the property values using
-///   [`Homie5ControllerProtocol::subscribe_props`]
-/// * after this you will start receiving [`Homie5Message::PropertyValue`] and
-///   ['Homie5Message::PropertyTarget`] messages for the properties of the device
+/// The `Homie5ControllerProtocol` struct provides the core functionality for generating MQTT subscription and publish commands required for interacting with Homie 5 devices.
+///
+/// This struct simplifies the process of discovering devices, subscribing to device attributes, handling device property changes, and sending commands or broadcasts to devices in the Homie MQTT protocol. It supports managing device discovery, subscriptions to device states and properties, and sending set commands and broadcast messages.
+///
+/// The `Homie5ControllerProtocol` is designed for use in Homie-based IoT controllers where efficient communication with multiple devices is required. It offers a straightforward interface for subscribing to device attributes and managing device properties.
+///
+/// # Usage
+///
+/// To create an instance of `Homie5ControllerProtocol`, use the `new` method. This struct provides methods for discovering devices, subscribing to device attributes and properties, and sending commands or broadcasts via MQTT topics.
+///
+/// # Example
+///
+/// ```rust
+/// use homie5::{Homie5ControllerProtocol, HomieDomain};
+///
+/// let protocol = Homie5ControllerProtocol::new();
+/// let subscriptions = protocol.discover_devices(&HomieDomain::Default);
+/// for subscription in subscriptions {
+///     // Handle each subscription
+/// }
+/// ```
+///
+/// The struct is intended for use in controller applications interacting with multiple Homie devices, enabling efficient subscription management and MQTT communication.
 #[derive(Default)]
 pub struct Homie5ControllerProtocol {}
 
 impl Homie5ControllerProtocol {
-    /// Create a new Homie5ControllerProtocol object
+    /// Creates a new `Homie5ControllerProtocol` instance.
+    ///
+    /// # Returns
+    /// A new `Homie5ControllerProtocol` object initialized with default values.
     pub fn new() -> Self {
         Default::default()
     }
 
+    /// Generates a subscription to discover Homie devices by subscribing to the `$state` attribute of all devices.
+    ///
+    /// # Parameters
+    /// - `homie_domain`: The Homie domain in which to discover devices.
+    ///
+    /// # Returns
+    /// An iterator over a `Subscription` object that subscribes to the `$state` attribute of all devices in the specified domain.
     pub fn discover_devices<'a>(&'a self, homie_domain: &HomieDomain) -> impl Iterator<Item = Subscription> + 'a {
         iter::once(Subscription {
             topic: format!("{}/{}/+/{}", homie_domain, HOMIE_VERSION, DEVICE_ATTRIBUTE_STATE),
             qos: QoS::ExactlyOnce,
         })
     }
 
+    /// Generates subscriptions for all attributes of a specified device, excluding `$state`.
+    ///
+    /// # Parameters
+    /// - `device`: A reference to the `DeviceRef` that identifies the device.
+    ///
+    /// # Returns
+    /// An iterator over `Subscription` objects for the device's attributes (e.g., `$log`, `$description`, `$alert`).
     pub fn subscribe_device<'a>(&'a self, device: &'a DeviceRef) -> impl Iterator<Item = Subscription> + 'a {
         DEVICE_ATTRIBUTES
             .iter()
-            .skip(1) // Skip the $state attribute (which must be first in the array)
+            .skip(1) // Skip the $state attribute
             .map(move |attribute| {
                 if *attribute == DEVICE_ATTRIBUTE_ALERT {
                     Subscription {
@@ -54,6 +100,13 @@ impl Homie5ControllerProtocol {
             })
     }
 
+    /// Generates unsubscribe requests for all attributes of a specified device, excluding `$state`.
+    ///
+    /// # Parameters
+    /// - `device`: A reference to the `DeviceRef` that identifies the device.
+    ///
+    /// # Returns
+    /// An iterator over `Unsubscribe` objects for the device's attributes (e.g., `$log`, `$description`, `$alert`).
     pub fn unsubscribe_device<'a>(&'a self, device: &'a DeviceRef) -> impl Iterator<Item = Unsubscribe> + 'a {
         DEVICE_ATTRIBUTES.iter().skip(1).map(move |attribute| {
             if *attribute == DEVICE_ATTRIBUTE_ALERT {
@@ -68,6 +121,14 @@ impl Homie5ControllerProtocol {
         })
     }
 
+    /// Subscribes to all properties of a device as described in the provided `HomieDeviceDescription`.
+    ///
+    /// # Parameters
+    /// - `device`: A reference to the `DeviceRef` that identifies the device.
+    /// - `description`: A reference to the `HomieDeviceDescription` that describes the device's properties.
+    ///
+    /// # Returns
+    /// An iterator over `Subscription` objects for the device's properties.
     pub fn subscribe_props<'a>(
         &'a self,
         device: &'a DeviceRef,
@@ -95,6 +156,14 @@ impl Homie5ControllerProtocol {
         })
     }
 
+    /// Unsubscribes from all properties of a device based on its `HomieDeviceDescription`.
+    ///
+    /// # Parameters
+    /// - `device`: A reference to the `DeviceRef` that identifies the device.
+    /// - `description`: A reference to the `HomieDeviceDescription` that describes the device's properties.
+    ///
+    /// # Returns
+    /// An iterator over `Unsubscribe` objects for the device's properties.
     pub fn unsubscribe_props<'a>(
         &'a self,
         device: &'a DeviceRef,
@@ -106,6 +175,17 @@ impl Homie5ControllerProtocol {
         })
     }
 
+    /// Publishes a set command to change a property's value.
+    ///
+    /// # Parameters
+    /// - `homie_domain`: The Homie domain in which the device is located.
+    /// - `device_id`: The ID of the device.
+    /// - `node_id`: The ID of the node the property belongs to.
+    /// - `prop_id`: The ID of the property.
+    /// - `value`: The new value to set for the property.
+    ///
+    /// # Returns
+    /// A `Publish` object containing the set command to be sent to the MQTT broker.
     pub fn set_command_ids(
         &self,
         homie_domain: &HomieDomain,
@@ -125,7 +205,14 @@ impl Homie5ControllerProtocol {
         }
     }
 
-    //pub fn set_command(&self, prop: &PropertyIdentifier, value: impl Into<String>) -> Publish {
+    /// Publishes a set command for a property using a `PropertyRef`.
+    ///
+    /// # Parameters
+    /// - `prop`: A reference to the `PropertyRef` identifying the property.
+    /// - `value`: The new value to set for the property.
+    ///
+    /// # Returns
+    /// A `Publish` object containing the set command to be sent to the MQTT broker.
     pub fn set_command(&self, prop: &PropertyRef, value: &HomieValue) -> Publish {
         self.set_command_ids(
             &prop.node.device.homie_domain,
@@ -136,6 +223,15 @@ impl Homie5ControllerProtocol {
         )
     }
 
+    /// Sends a broadcast message to all devices in the specified Homie domain.
+    ///
+    /// # Parameters
+    /// - `homie_domain`: The Homie domain in which to send the broadcast.
+    /// - `broadcast_topic`: The topic of the broadcast.
+    /// - `broadcast_message`: The content of the broadcast message.
+    ///
+    /// # Returns
+    /// A `Publish` object representing the broadcast message to be sent to the MQTT broker.
     pub fn send_broadcast(
         &self,
         homie_domain: &HomieDomain,
@@ -153,12 +249,27 @@ impl Homie5ControllerProtocol {
         }
     }
 
+    /// Subscribes to broadcast messages in the specified Homie domain.
+    ///
+    /// # Parameters
+    /// - `homie_domain`: The Homie domain in which to subscribe to broadcasts.
+    ///
+    /// # Returns
+    /// An iterator over a `Subscription` object that subscribes to broadcast messages.
     pub fn subscribe_broadcast<'a>(&'a self, homie_domain: &HomieDomain) -> impl Iterator<Item = Subscription> + 'a {
         iter::once(Subscription {
             topic: format!("{}/{}/$broadcast/#", homie_domain, HOMIE_VERSION),
             qos: QoS::ExactlyOnce,
         })
     }
+
+    /// Unsubscribes from broadcast messages in the specified Homie domain.
+    ///
+    /// # Parameters
+    /// - `homie_domain`: The Homie domain in which to unsubscribe from broadcasts.
+    ///
+    /// # Returns
+    /// An iterator over an `Unsubscribe` object that unsubscribes from broadcast messages.
     pub fn unsubscribe_broadcast<'a>(&'a self, homie_domain: &HomieDomain) -> impl Iterator<Item = Unsubscribe> + 'a {
         iter::once(Unsubscribe {
             topic: format!("{}/{}/$broadcast/#", homie_domain, HOMIE_VERSION),

src/device_description/builder.rs

@@ -1,3 +1,14 @@
+//! This module provides builders for constructing descriptions of Homie devices, nodes, and properties.
+//! The builders allow for flexible and incremental building of `HomieDeviceDescription`,
+//! `HomieNodeDescription`, and `HomiePropertyDescription` objects, commonly used in the Homie protocol.
+//!
+//! # Conditional Building
+//!
+//! All builders in this module offer the `do_if` method, which allows for executing a closure
+//! only if a certain condition is met. This is useful for adding optional elements or applying logic
+//! based on runtime conditions.
+//!
+//! ```
 use crate::{HomieDataType, HomieID, HOMIE_VERSION_FULL};
 
 use super::{
@@ -6,6 +17,21 @@ use super::{
 };
 use std::collections::{hash_map, HashMap};
 
+/// Builder for constructing `HomieDeviceDescription` objects.
+///
+/// The `DeviceDescriptionBuilder` helps construct a complete `HomieDeviceDescription` by setting attributes
+/// like children, nodes, extensions, and device metadata. It provides flexibility in handling device structure
+/// and content, allowing for customization at each step.
+///
+/// ### Example Usage
+/// ```rust
+/// use homie5::device_description::*;
+/// let device_description = DeviceDescriptionBuilder::new()
+///     .name(Some("MyDevice".to_string()))
+///     .add_child("node1".try_into().unwrap())
+///     .add_extension("com.example.extension".to_string())
+///     .build();
+/// ```
 pub struct DeviceDescriptionBuilder {
     description: HomieDeviceDescription,
 }
@@ -119,6 +145,20 @@ impl DeviceDescriptionBuilder {
     }
 }
 
+/// Builder for constructing `HomieNodeDescription` objects.
+///
+/// The `NodeDescriptionBuilder` simplifies the creation of `HomieNodeDescription` instances.
+/// Nodes are the intermediate layer between devices and properties, and this builder facilitates
+/// adding properties, setting the node name and type, and optionally removing or replacing properties.
+///
+/// ### Example Usage
+/// ```rust
+/// use homie5::device_description::*;
+/// let node_description = NodeDescriptionBuilder::new()
+///     .name(Some("TemperatureNode".to_string()))
+///     .r#type("sensor")
+///     .build();
+/// ```
 pub struct NodeDescriptionBuilder {
     description: HomieNodeDescription,
 }
@@ -212,6 +252,24 @@ impl NodeDescriptionBuilder {
     }
 }
 
+/// Builder for constructing `HomiePropertyDescription` objects.
+///
+/// The `PropertyDescriptionBuilder` is designed for constructing `HomiePropertyDescription`
+/// objects, which represent individual properties of a node, such as sensor readings or settings.
+/// Properties have attributes like datatype, format, settable, and retained, which can be set using
+/// this builder.
+///
+/// ### Example Usage
+/// ```rust
+/// use homie5::device_description::*;
+/// use homie5::*;
+/// let property_description = PropertyDescriptionBuilder::new(HomieDataType::Float)
+///     .name(Some("Temperature".to_string()))
+///     .settable(false)
+///     .retained(true)
+///     .unit(Some("°C".to_string()))
+///     .build();
+/// ```
 pub struct PropertyDescriptionBuilder {
     description: HomiePropertyDescription,
 }

src/device_description/mod.rs

@@ -1,3 +1,5 @@
+//! This module provides all types and tools to create (builders) and manage homie device, node and property
+//! descriptions.
 use std::collections::hash_map::DefaultHasher;
 use std::hash::Hasher;
 use std::iter::Iterator;