documentation

Author: rex-schilasky

rustecal-types-bytes/src/lib.rs

@@ -1,9 +1,25 @@
+//! `rustecal-types-bytes` provides typed support for raw byte messages over eCAL.
+//!
+//! This crate defines a wrapper type `BytesMessage` that implements the
+//! [`PublisherMessage`] and [`SubscriberMessage`] traits from the `rustecal` crate,
+//! enabling ergonomic and type-safe publishing and subscribing of binary blobs.
+
 use rustecal::{PublisherMessage, SubscriberMessage};
 use rustecal::pubsub::types::DataTypeInfo;
 
+/// A wrapper for raw binary data transmitted via eCAL.
+///
+/// This message type is ideal for non-structured byte payloads such as images,
+/// serialized custom formats, or arbitrary buffers.
+///
+/// Implements both [`PublisherMessage`] and [`SubscriberMessage`] to support
+/// bidirectional pub/sub use.
 pub struct BytesMessage(pub Vec<u8>);
 
 impl SubscriberMessage for BytesMessage {
+    /// Returns metadata describing the message encoding and type.
+    ///
+    /// Encoding is `"raw"`, type name is `"bytes"`, and no descriptor is included.
     fn datatype() -> DataTypeInfo {
         DataTypeInfo {
             encoding: "raw".into(),
@@ -12,16 +28,19 @@ impl SubscriberMessage for BytesMessage {
         }
     }
 
+    /// Creates a `BytesMessage` from a raw byte slice.
     fn from_bytes(bytes: &[u8]) -> Option<Self> {
         Some(BytesMessage(bytes.to_vec()))
     }
 }
 
 impl PublisherMessage for BytesMessage {
+    /// Reuses the `SubscriberMessage::datatype()` implementation.
     fn datatype() -> DataTypeInfo {
         <BytesMessage as SubscriberMessage>::datatype()
     }
 
+    /// Converts the internal byte vector into a byte slice for sending.
     fn to_bytes(&self) -> Vec<u8> {
         self.0.clone()
     }

rustecal-types-protobuf/src/lib.rs

@@ -1,18 +1,59 @@
+//! Typed Protobuf message support for `rustecal`.
+//!
+//! This crate provides a wrapper around `prost::Message`-based types, allowing
+//! seamless integration with `TypedPublisher` and `TypedSubscriber` from the `rustecal` API.
+//!
+//! ## Usage
+//!
+//! To publish or subscribe to Protobuf messages, wrap your message type in `ProtobufMessage<T>`
+//! and ensure the inner type implements both `prost::Message` and `IsProtobufType`.
+//!
+//! ```rust
+//! use rustecal_types_protobuf::{ProtobufMessage, IsProtobufType};
+//! use my_proto::MyMessage;
+//!
+//! impl IsProtobufType for MyMessage {}
+//!
+//! let msg = ProtobufMessage(MyMessage::default());
+//! ```
+
 use prost::Message;
 use rustecal::pubsub::{PublisherMessage, SubscriberMessage};
 use rustecal::pubsub::types::DataTypeInfo;
 
-/// Marker trait to opt-in for Protobuf support
+/// Marker trait to opt-in a Protobuf type for use with eCAL.
+///
+/// This trait must be implemented for any `prost::Message` you wish to use
+/// with `ProtobufMessage<T>`. It provides a type-level opt-in mechanism
+/// to ensure users are aware of what's being exposed to eCAL.
 pub trait IsProtobufType {}
 
-/// Wrapper around a `prost::Message` to enable use with TypedPublisher and TypedSubscriber
+/// Wrapper around a `prost::Message` type to enable typed publishing and subscription.
+///
+/// This is the type that should be used with `TypedPublisher` and `TypedSubscriber`
+/// for Protobuf messages.
+///
+/// ```rust
+/// use rustecal_types_protobuf::{ProtobufMessage, IsProtobufType};
+/// use my_proto::MyMessage;
+///
+/// impl IsProtobufType for MyMessage {}
+///
+/// let wrapped = ProtobufMessage(MyMessage::default());
+/// ```
 #[derive(Debug, Clone)]
 pub struct ProtobufMessage<T>(pub T);
 
 impl<T> SubscriberMessage for ProtobufMessage<T>
 where
     T: Message + Default + IsProtobufType,
 {
+    /// Returns metadata used by eCAL to describe the Protobuf type.
+    ///
+    /// This includes:
+    /// - `proto` as encoding
+    /// - the Rust type name
+    /// - an optional descriptor (currently empty)
     fn datatype() -> DataTypeInfo {
         DataTypeInfo {
             encoding: "proto".to_string(),
@@ -21,6 +62,11 @@ where
         }
     }
 
+    /// Decodes a Protobuf message from bytes.
+    ///
+    /// # Returns
+    /// - `Some(ProtobufMessage<T>)` on success
+    /// - `None` if decoding fails
     fn from_bytes(bytes: &[u8]) -> Option<Self> {
         T::decode(bytes).ok().map(ProtobufMessage)
     }
@@ -30,10 +76,15 @@ impl<T> PublisherMessage for ProtobufMessage<T>
 where
     T: Message + Default + IsProtobufType,
 {
+    /// Returns the same datatype information as [`SubscriberMessage`] implementation.
     fn datatype() -> DataTypeInfo {
         <ProtobufMessage<T> as SubscriberMessage>::datatype()
     }
 
+    /// Encodes the message to a byte buffer.
+    ///
+    /// # Panics
+    /// Will panic if `prost::Message::encode` fails (should never panic for valid messages).
     fn to_bytes(&self) -> Vec<u8> {
         let mut buf = Vec::with_capacity(self.0.encoded_len());
         self.0

rustecal-types-string/src/lib.rs

@@ -1,10 +1,24 @@
+//! # rustecal-types-string
+//!
+//! This crate provides support for sending and receiving UTF-8 string messages
+//! using the `rustecal` typed publisher and subscriber APIs.
+//!
+//! It defines a wrapper type [`StringMessage`] that implements the necessary traits
+//! [`PublisherMessage`] and [`SubscriberMessage`] for type-safe usage with
+//! [`TypedPublisher`] and [`TypedSubscriber`] respectively.
+
 use rustecal::{PublisherMessage, SubscriberMessage};
 use rustecal::pubsub::types::DataTypeInfo;
 use std::str;
 
+/// A wrapper for UTF-8 string messages used with typed eCAL pub/sub.
+///
+/// This type allows sending and receiving strings through the
+/// `TypedPublisher<StringMessage>` and `TypedSubscriber<StringMessage>` APIs.
 pub struct StringMessage(pub String);
 
 impl SubscriberMessage for StringMessage {
+    /// Returns metadata describing this message type (`utf-8` encoded string).
     fn datatype() -> DataTypeInfo {
         DataTypeInfo {
             encoding: "utf-8".to_string(),
@@ -13,16 +27,19 @@ impl SubscriberMessage for StringMessage {
         }
     }
 
+    /// Attempts to decode a UTF-8 string from a byte buffer.
     fn from_bytes(bytes: &[u8]) -> Option<Self> {
         str::from_utf8(bytes).ok().map(|s| StringMessage(s.to_string()))
     }
 }
 
 impl PublisherMessage for StringMessage {
+    /// Returns the same metadata as [`SubscriberMessage::datatype`].
     fn datatype() -> DataTypeInfo {
         <StringMessage as SubscriberMessage>::datatype()
     }
 
+    /// Serializes the string into a byte buffer.
     fn to_bytes(&self) -> Vec<u8> {
         self.0.as_bytes().to_vec()
     }

rustecal/src/ecal/components.rs

@@ -1,22 +1,62 @@
+//! Component selection for eCAL initialization.
+//!
+//! This module provides the [`EcalComponents`] bitflag struct used to specify
+//! which parts of the eCAL middleware should be activated during initialization.
+//!
+//! The flags can be combined using bitwise OR operations (e.g., `PUBLISHER | LOGGING`).
+//!
+//! These flags are passed to [`crate::ecal::core::Ecal::initialize`] to enable
+//! or disable subsystems for performance, resource usage, or system design reasons.
+
 use bitflags::bitflags;
 
 bitflags! {
+    /// Bitflags representing the subsystems of eCAL that can be individually enabled.
+    ///
+    /// These flags are used with [`Ecal::initialize`](crate::ecal::core::Ecal::initialize)
+    /// to control which components are active.
     #[derive(Default)]
     pub struct EcalComponents: u32 {
+        /// Disable all components (no subsystems enabled).
         const NONE       = 0x000;
+
+        /// Enable the publish interface.
         const PUBLISHER  = 0x001;
+
+        /// Enable the subscribe interface.
         const SUBSCRIBER = 0x002;
+
+        /// Enable eCAL service (RPC-style communication).
         const SERVICE    = 0x004;
+
+        /// Enable the monitoring component (e.g., for visualizing in eCAL Monitor).
         const MONITORING = 0x008;
+
+        /// Enable logging (console/file output from eCAL runtime).
         const LOGGING    = 0x010;
+
+        /// Enable time synchronization (e.g., simulated time or global time sync).
         const TIMESYNC   = 0x020;
 
+        /// Common default configuration used for most applications.
+        ///
+        /// This enables all major communication components:
+        /// - `PUBLISHER`
+        /// - `SUBSCRIBER`
+        /// - `SERVICE`
+        /// - `LOGGING`
+        /// - `TIMESYNC`
+        ///
+        /// It does **not** include `MONITORING`, which can be enabled separately.
         const DEFAULT = Self::PUBLISHER.bits()
                       | Self::SUBSCRIBER.bits()
                       | Self::SERVICE.bits()
                       | Self::LOGGING.bits()
                       | Self::TIMESYNC.bits();
 
+        /// Enables all available components.
+        ///
+        /// This is equivalent to enabling every individual flag.
         const ALL     = Self::PUBLISHER.bits()
                       | Self::SUBSCRIBER.bits()
                       | Self::SERVICE.bits()

rustecal/src/ecal/core.rs

@@ -1,11 +1,36 @@
+//! Core lifecycle control for the eCAL runtime.
+//!
+//! This module provides safe Rust wrappers around initializing and finalizing
+//! the eCAL communication system, as well as querying its state.
+//!
+//! The main entry point is the [`Ecal`] struct which provides:
+//! - [`Ecal::initialize`] to start the middleware
+//! - [`Ecal::finalize`] to shut it down
+//! - [`Ecal::ok`] to query if eCAL is currently running
+//!
+//! Typically, you will call [`Ecal::initialize`] once at the beginning of your
+//! application and [`Ecal::finalize`] at shutdown.
+
 use std::ffi::CString;
 use crate::ecal::components::EcalComponents;
 use rustecal_sys;
 
+/// Provides access to the core initialization and finalization functions of eCAL.
 pub struct Ecal;
 
 impl Ecal {
-    /// Initialize eCAL with specific components
+    /// Initializes the eCAL runtime system.
+    ///
+    /// This function must be called before using any publisher or subscriber functionality.
+    ///
+    /// # Arguments
+    ///
+    /// * `unit_name` - Optional name to identify this process in eCAL (e.g. in monitoring).
+    /// * `components` - Bitmask of which subsystems (e.g. pub/sub, monitoring) to enable.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` on success, or `Err(code)` with a non-zero error code.
     pub fn initialize(unit_name: Option<&str>, components: EcalComponents) -> Result<(), i32> {
         let cstr = unit_name.map(|s| CString::new(s).unwrap());
         let ptr = cstr.as_ref().map_or(std::ptr::null(), |c| c.as_ptr());
@@ -21,14 +46,22 @@ impl Ecal {
         }
     }
 
-    /// Finalize eCAL
+    /// Finalizes and shuts down the eCAL runtime system.
+    ///
+    /// After calling this function, all publishers and subscribers are invalidated.
     pub fn finalize() {
         unsafe {
             rustecal_sys::eCAL_Finalize();
         }
     }
 
-    /// Check if eCAL is running and in a valid state
+    /// Checks if the eCAL system is initialized and running properly.
+    ///
+    /// This can be used as the main loop condition in long-running processes.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the system is operational, `false` otherwise.
     pub fn ok() -> bool {
         unsafe { rustecal_sys::eCAL_Ok() != 0 }
     }

rustecal/src/pubsub/mod.rs

@@ -1,9 +1,29 @@
+//! Typed and untyped eCAL publish-subscribe API.
+//!
+//! This module provides both low-level and high-level publish-subscribe functionality.
+//!
+//! ## Modules
+//!
+//! - [`publisher`] and [`subscriber`] offer low-level wrappers over the C eCAL pub/sub API.
+//! - [`typed_publisher`] and [`typed_subscriber`] offer type-safe, generic Rust APIs with
+//!   automatic serialization and callback handling.
+//!
+//! ## Re-exports
+//!
+//! The traits and wrappers from the typed API are re-exported at this level for convenience:
+//!
+//! ```rust
+//! use rustecal::TypedPublisher;
+//! use rustecal::TypedSubscriber;
+//! ```
+
 pub mod types;
 pub mod publisher;
 pub mod subscriber;
 
 pub mod typed_subscriber;
 pub mod typed_publisher;
 
+// Publicly re-export high-level typed pub/sub traits and wrappers
 pub use typed_subscriber::{TypedSubscriber, SubscriberMessage};
 pub use typed_publisher::{TypedPublisher, PublisherMessage};