iox-#4 Document public API

README.md

@@ -15,7 +15,7 @@ Safe Rust bindings for [Eclipse iceoryx](https://github.com/eclipse-iceoryx/iceo
 2. [Examples](#examples)
     - [How to start RouDi](#how-to-start-roudi)
     - [Run the simple publisher and subscriber example](#run-the-simple-publisher-and-subscriber-example)
-3. [API by Example](#api-by-example)
+3. [How to write a simple application](#how-to-write-a-simple-application)
 4. [Limitations](#limitations)
 
 ## About
@@ -113,7 +113,7 @@ If `RouDi` is not running you get this output.
 
 After a waiting period, the application will shut down.
 
-## API by Example
+## How to write a simple application
 
 This is a brief API guide how to write a simple application.
 

iceoryx-sys/src/runtime.rs

@@ -15,9 +15,15 @@ cpp! {{
     using iox::runtime::PoshRuntime;
 }}
 
+/// The runtime that is needed for each application to communicate with the `RouDi` daemon
 pub struct Runtime {}
 
 impl Runtime {
+    /// With this associated function the application registers at `RouDi`
+    ///
+    /// The call to this function is required in order to create publisher and subscriber and must be done early
+    /// in the application startup. There cannot be two application with the same `app_name` be registered
+    /// simultaneously at `RouDi`.
     pub fn init(app_name: &str) {
         let app_name = CString::new(app_name).expect("CString::new failed");
         let app_name = app_name.as_ptr();

src/error.rs

@@ -4,19 +4,27 @@
 
 use thiserror::Error;
 
+/// Error which can occur when using iceoryx
 #[derive(Error, Debug)]
 pub enum IceoryxError {
+    /// Loaning a sample failed, e.g. due to exhausted memory pools.
     #[error("Could not loan sample")]
     LoanSampleFailed,
+    /// The requested alignment is invalid, e.g. smaller than required by the underlying type
     #[error("Invalid alignment! Requested: {requested}; Min required: {min_required} ")]
     InvalidAlignment {
+        /// The requested alignment
         requested: usize,
+        /// The required minimal alignment
         min_required: usize,
     },
+    /// Creation of the publisher failed, e.g. due to exhausted resources
     #[error("Could not create publisher")]
     PublisherCreationFailed,
+    /// Creation of the subscriber failed, e.g. due to exhausted resources
     #[error("Could not create subscriber")]
     SubscriberCreationFailed,
+    /// The number of maximum number of samples hold in parallel is exhausted
     #[error("Number of allowed samples to hold is exhausted")]
     TooManySamplesHoldInParallel,
 }

src/introspection/memory.rs

@@ -8,11 +8,13 @@ use crate::{InactiveSubscriber, SubscriberBuilder};
 
 use std::marker::PhantomData;
 
+/// Introspection for used memory and shared memory segments
 pub struct MemPoolIntrospection {
     phantom: PhantomData<()>,
 }
 
 impl MemPoolIntrospection {
+    /// Creates a subscriber for the MemPool introspection
     #[allow(clippy::new_ret_no_self)]
     pub fn new() -> Result<InactiveSubscriber<MemPoolIntrospectionTopic>, IceoryxError> {
         SubscriberBuilder::<MemPoolIntrospectionTopic>::new("Introspection", "RouDi_ID", "MemPool")

src/introspection/mod.rs

@@ -2,6 +2,8 @@
 // SPDX-FileCopyrightText: © Contributors to the iceoryx-rs project
 // SPDX-FileContributor: Mathias Kraus
 
+//! Introspection related structs and enums
+
 mod memory;
 pub use memory::MemPoolIntrospection;
 

src/introspection/port.rs

@@ -8,11 +8,13 @@ use crate::{InactiveSubscriber, SubscriberBuilder};
 
 use std::marker::PhantomData;
 
+/// Introspection for publisher and subscriber ports
 pub struct PortIntrospection {
     phantom: PhantomData<()>,
 }
 
 impl PortIntrospection {
+    /// Creates a subscriber for the port introspection
     #[allow(clippy::new_ret_no_self)]
     pub fn new() -> Result<InactiveSubscriber<PortIntrospectionTopic>, IceoryxError> {
         SubscriberBuilder::<PortIntrospectionTopic>::new("Introspection", "RouDi_ID", "Port")

src/introspection/process.rs

@@ -8,11 +8,13 @@ use crate::{InactiveSubscriber, SubscriberBuilder};
 
 use std::marker::PhantomData;
 
+/// Introspection for registered processes
 pub struct ProcessIntrospection {
     phantom: PhantomData<()>,
 }
 
 impl ProcessIntrospection {
+    /// Creates a subscriber for the process introspection
     #[allow(clippy::new_ret_no_self)]
     pub fn new() -> Result<InactiveSubscriber<ProcessIntrospectionTopic>, IceoryxError> {
         SubscriberBuilder::<ProcessIntrospectionTopic>::new("Introspection", "RouDi_ID", "Process")

src/lib.rs

@@ -2,6 +2,35 @@
 // SPDX-FileCopyrightText: © Contributors to the iceoryx-rs project
 // SPDX-FileContributor: Mathias Kraus
 
+#![warn(missing_docs)]
+
+//! # iceoryx-rs
+//!
+//! Eclipse iceoryx is a true zero-copy, inter-process communication framework with the goal to boost
+//! autonomous driving with their demand on high data throughput and low latency. With its bandwidth and speed,
+//! iceoryx also fits well into other domains where low latency and transmitting large data structures
+//! is a concern. If you would like to know more about Eclipse iceoryx you can take a look at the
+//! `Getting started` section on [iceoryx.io](https://iceoryx.io) or the
+//! [README.md](https://github.com/eclipse-iceoryx/iceoryx/blob/master/README.md) of the main project.
+//!
+//! The Rust bindings are a work in progress and currently support only the pub-sub messaging pattern.
+//! Upcoming releases will close the gap and the goal is to have the Rust bindings as a first class citizen
+//! in the iceoryx ecosystem.
+//!
+//! This project started with the goal to create an awesome looking introspection TUI in Rust and led to
+//! [iceray](https://crates.io/crates/iceray). Check it out.
+//!
+//! # Limitations
+//!
+//! Currently, only a subset of Eclipse iceoryx v2.0 is supported and some features are missing.
+//!
+//! - [x] pub-sub messaging pattern
+//! - [ ] user defined header for pub-sub data
+//! - [ ] request-response messaging pattern
+//! - [ ] `Listener` and `WaitSet`
+//! - [ ] lookup of available services aka `ServiceDiscovery`
+//! - [x] accessing introspection topics like memory usage and available publisher and subscriber
+
 pub mod introspection;
 pub mod marker;
 
@@ -15,27 +44,40 @@ pub use publisher::PublisherBuilder;
 
 mod subscriber;
 pub use subscriber::InactiveSubscriber;
+pub use subscriber::Subscriber;
 pub use subscriber::SubscriberBuilder;
 
 mod sample_mut;
 pub use sample_mut::SampleMut;
 
 mod sample;
+pub use sample::Sample;
+pub use sample::SampleReceiver;
 pub use sample::SampleReceiverWaitState;
 
 pub mod st {
+    //! Single-threaded restricted subscriber
+
     use super::*;
 
+    /// A [`Sample`](sample::Sample) from a single-threaded subscriber
     pub type Sample<T> = sample::Sample<T, ffi::SubscriberRc>;
+    /// A [`SampleReceiver`](sample::SampleReceiver) from a single-threaded subscriber
     pub type SampleReceiver<T> = sample::SampleReceiver<T, ffi::SubscriberRc>;
+    /// A single-threaded [`Subscriber`](subscriber::Subscriber)
     pub type Subscriber<T> = subscriber::Subscriber<T, ffi::SubscriberRc>;
 }
 
 pub mod mt {
+    //! Multi-threaded capable subscriber
+
     use super::*;
 
+    /// A [`Sample`](sample::Sample) from a multi-threaded subscriber
     pub type Sample<T> = sample::Sample<T, ffi::SubscriberArc>;
+    /// A [`SampleReceiver`](sample::SampleReceiver) from a multi-threaded subscriber
     pub type SampleReceiver<T> = sample::SampleReceiver<T, ffi::SubscriberArc>;
+    /// A multi-threaded [`Subscriber`](subscriber::Subscriber)
     pub type Subscriber<T> = subscriber::Subscriber<T, ffi::SubscriberArc>;
 }
 

src/marker.rs

@@ -2,11 +2,17 @@
 // SPDX-FileCopyrightText: © Contributors to the iceoryx-rs project
 // SPDX-FileContributor: Mathias Kraus
 
+//! Marker traits for iceoryx-rs
+
 use std::mem::MaybeUninit;
 
+/// This is a marker trait for types that can be transferred via shared memory.
+///
+/// The `ShmSend` marker trait is similar to the `Send` marker trait which is used for types that
+/// can be transferred across thread boundaries. `ShmSend` marks types for a transfer across process boundaries.
+///
 /// # Safety
 ///
-/// This is a marker trait for types that can be transferred via shared memory.
 /// The types must satisfy the following constraints:
 /// - no heap is used
 /// - the data structure is entirely contained in the shared memory - no pointers
@@ -16,6 +22,8 @@ use std::mem::MaybeUninit;
 /// - the type must not implement `Drop`; `drop` will not be called when the memory is released
 ///   since the memory might be located in a shm segment without write access to the subscriber
 /// In general, types that could implement the Copy trait fulfill these requirements.
+///
+/// For interoperability with C and C++ the types should also be `#[repr(C)]`.
 pub unsafe trait ShmSend {}
 
 unsafe impl ShmSend for bool {}