[eclipse-iceoryx#4] Add documentation for container crate

Author: elfenpiff

iceoryx2-bb/container/src/byte_string.rs

@@ -12,7 +12,7 @@
 
 //! Relocatable (inter-process shared memory compatible) string implementations.
 //!
-//! The [`FixedSizeByteString`] has a fixed capacity defined at compile time.
+//! The [`FixedSizeByteString`](crate::byte_string::FixedSizeByteString) has a fixed capacity defined at compile time.
 //!
 //! # Example
 //!
@@ -80,7 +80,6 @@ pub struct FixedSizeByteString<const CAPACITY: usize> {
 }
 
 unsafe impl<const CAPACITY: usize> Send for FixedSizeByteString<CAPACITY> {}
-unsafe impl<const CAPACITY: usize> Sync for FixedSizeByteString<CAPACITY> {}
 
 impl<const CAPACITY: usize, const CAPACITY_OTHER: usize>
     PartialOrd<FixedSizeByteString<CAPACITY_OTHER>> for FixedSizeByteString<CAPACITY>
@@ -191,6 +190,7 @@ impl<const CAPACITY: usize> Default for FixedSizeByteString<CAPACITY> {
     }
 }
 
+// Adds escape characters to the string so that it can be used for console output.
 pub fn as_escaped_string(bytes: &[u8]) -> String {
     String::from_utf8(
         bytes
@@ -403,6 +403,7 @@ impl<const CAPACITY: usize> FixedSizeByteString<CAPACITY> {
     ///  * The 'idx' must by less than [`FixedSizeByteString::len()`].
     ///  * The 'bytes.len()' must be less or equal than [`FixedSizeByteString::capacity()`] -
     ///    [`FixedSizeByteString::len()`]
+    ///
     pub unsafe fn insert_bytes_unchecked(&mut self, idx: usize, bytes: &[u8]) {
         unsafe {
             std::ptr::copy(

iceoryx2-bb/container/src/lib.rs

@@ -10,10 +10,85 @@
 //
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-//! Contains standard container which are compatible with an inter-process shared memory usage.
+//! # Iceoryx2 Building Blocks (BB) Container
+//!
+//! This is a support library for iceoryx2 which comes with containers that are
+//! compatible with shared memory and can be used to construct custom payload types for
+//! inter-process communication.
+//!
+//! Most containers come in 3 variations:
+//!  1. `FixedSize***`, compile-time fixed size version. The capacity must be known at compile
+//!     time.
+//!  2. `Relocatable***`, run-time fixed size version that is shared memory compatible. The
+//!     capacity must be known when the object is created. **This object is not movable!**
+//!  3. `***`, run-time fixed size version that is **not** shared memory compatible but can be
+//!     moved.
+//!
+//! # Example
+//!
+//! ## 1. Compile-Time FixedSize Containers
+//!
+//! We create a struct consisting of compile-time fixed size containers that can be used for
+//! zero copy inter-process communication.
+//!
+//! ```
+//! use iceoryx2_bb_container::byte_string::*;
+//! use iceoryx2_bb_container::vec::*;
+//!
+//! const TEXT_CAPACITY: usize = 123;
+//! const DATA_CAPACITY: usize = 456;
+//!
+//! #[repr(C)]
+//! struct MyMessageType {
+//!     some_text: FixedSizeByteString<TEXT_CAPACITY>,
+//!     some_data: FixedSizeVec<u64, DATA_CAPACITY>,
+//! }
+//!
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! let my_message = MyMessageType {
+//!     some_text: FixedSizeByteString::from_bytes(b"Hello World")?,
+//!     some_data: FixedSizeVec::new(),
+//! };
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ## 2. Shared Memory Compatible Run-Time FixedSize Containers
+//!
+//! Despite that the containers are already implemented, iceoryx2 itself does not yet support
+//! run-time fixed size types. It is planned and will come.
+//!
+//! ## 3. Run-Time FixedSize Containers
+//!
+//! We create a struct consisting of run-time fixed size containers. This can be interesting when
+//! it shall be used in a safety-critical environment where everything must be pre-allocated to
+//! ensure that required memory is always available.
+//!
+//! ```
+//! use iceoryx2_bb_container::queue::*;
+//!
+//! const QUEUE_CAPACITY: usize = 123;
+//!
+//! #[repr(C)]
+//! struct MyType {
+//!     some_queue: Queue<u64>,
+//! }
+//!
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! let my_thing = MyType {
+//!     some_queue: Queue::new(QUEUE_CAPACITY),
+//! };
+//! # Ok(())
+//! # }
+//! ```
 
+/// A byte string similar to [`std::string::String`] but it does not support UTF-8
 pub mod byte_string;
+/// A queue similar to [`std::collections::VecDeque`]
 pub mod queue;
+/// Extends the [ByteString](crate::byte_string) so that custom string types with a semantic
+/// ruleset on their content can be realized.
 #[macro_use]
 pub mod semantic_string;
+/// A vector similar to [`std::vec::Vec`]
 pub mod vec;

iceoryx2-bb/container/src/queue.rs

@@ -12,13 +12,13 @@
 
 //! Two relocatable (inter process shared memory compatible) queues.
 //!
-//! The [`Queue`] which has a
-//! fixed capacity defined at runtime and the [`FixedSizeQueue`] which has a fixed capacity at
-//! compile time.
+//! The [`Queue`](crate::queue::Queue) which has a
+//! fixed capacity defined at runtime and the [`FixedSizeQueue`](crate::queue::FixedSizeQueue)
+//! which has a fixed capacity at compile time.
 //!
 //! # Examples
 //!
-//! ## Create [`Queue`] inside constructs which provides memory
+//! ## Create [`Queue`](crate::queue::Queue) inside constructs which provides memory
 //!
 //! ```
 //! use iceoryx2_bb_container::queue::RelocatableQueue;
@@ -42,7 +42,7 @@
 //! }
 //! ```
 //!
-//! ## Create [`Queue`] with allocator
+//! ## Create [`Queue`](crate::queue::Queue) with allocator
 //!
 //! ```
 //! use iceoryx2_bb_container::queue::RelocatableQueue;

iceoryx2-bb/container/src/vec.rs

@@ -13,13 +13,13 @@
 //! Two relocatable (inter-process shared memory compatible) vector implementations.
 //!
 //!
-//! The [`Vec`] which has a
-//! fixed capacity defined at runtime and the [`FixedSizeVec`] which has a fixed capacity at
-//! compile time.
+//! The [`Vec`](crate::vec::Vec) which has a
+//! fixed capacity defined at runtime and the [`FixedSizeVec`](crate::vec::FixedSizeVec)
+//! which has a fixed capacity at compile time.
 //!
 //! # Examples
 //!
-//! ## Create [`Vec`] inside constructs which provides memory
+//! ## Create [`Vec`](crate::vec::Vec) inside constructs which provides memory
 //!
 //! ```
 //! use iceoryx2_bb_container::vec::Vec;
@@ -43,7 +43,7 @@
 //! }
 //! ```
 //!
-//! ## Create [`Vec`] with allocator
+//! ## Create [`Vec`](crate::vec::Vec) with allocator
 //!
 //! ```
 //! use iceoryx2_bb_container::vec::Vec;
@@ -88,7 +88,6 @@ pub struct Vec<T> {
 }
 
 unsafe impl<T: Send> Send for Vec<T> {}
-unsafe impl<T: Sync> Sync for Vec<T> {}
 
 impl<T> Drop for Vec<T> {
     fn drop(&mut self) {
@@ -367,7 +366,6 @@ impl<T: Clone, const CAPACITY: usize> Clone for FixedSizeVec<T, CAPACITY> {
 }
 
 unsafe impl<T: Send, const CAPACITY: usize> Send for FixedSizeVec<T, CAPACITY> {}
-unsafe impl<T: Sync, const CAPACITY: usize> Sync for FixedSizeVec<T, CAPACITY> {}
 
 impl<T, const CAPACITY: usize> FixedSizeVec<T, CAPACITY> {
     /// Creates a new vector.