[#498] Add more detailed documentation

eclipse-iceoryx · Nov 1, 2024 · f05cfb4 · f05cfb4
1 parent 4eaa0bf
commit f05cfb4
Show file tree

Hide file tree

Showing 4 changed files with 24 additions and 7 deletions.
diff --git a/doc/release-notes/iceoryx2-unreleased.md b/doc/release-notes/iceoryx2-unreleased.md
@@ -38,6 +38,7 @@
 * Rename `NodeEvent` into `WaitEvent` [#390](https://github.com/eclipse-iceoryx/iceoryx2/issues/390)
 * Bazel support for the Rust crates [#349](https://github.com/eclipse-iceoryx/iceoryx2/issues/349)
 * Remove ACL dependency [#457](https://github.com/eclipse-iceoryx/iceoryx2/issues/457)
+* Publish Subscribe Header contains number of elements contained in a `Sample` [#498](https://github.com/eclipse-iceoryx/iceoryx2/issues/498)
 
 ### Workflow
 
@@ -72,3 +73,11 @@
     // ...
    }
    ```
+
+2. Removed `payload_type_layout` from pub/sub header.
+
+    ```rust
+    // old
+    let sample = publisher.loan()?;
+    sample.header().payload_type_layout();
+    ```
diff --git a/iceoryx2/src/port/subscriber.rs b/iceoryx2/src/port/subscriber.rs
@@ -429,8 +429,6 @@ impl<Service: service::Service, Payload: Debug, UserHeader: Debug>
     pub fn receive(
         &self,
     ) -> Result<Option<Sample<Service, Payload, UserHeader>>, SubscriberReceiveError> {
-        debug_assert!(TypeId::of::<Payload>() != TypeId::of::<CustomPayloadMarker>());
-
         Ok(self.receive_impl()?.map(|(details, absolute_address)| {
             let header_ptr = absolute_address as *const Header;
             let user_header_ptr = self.user_header_ptr(header_ptr).cast();
@@ -480,9 +478,11 @@ impl<Service: service::Service, UserHeader: Debug>
     ///
     ///  * The number_of_elements in the [`Header`](crate::service::header::publish_subscribe::Header)
     ///     corresponds to the payload type details that where overridden in
-    ///     `MessageTypeDetails::payload.size`. Meaning, when the payload.size == 8 and the number
-    ///     of elements if 5, it means that the sample will contain a slice of 8 * 5 = 40
-    ///     [`CustomPayloadMarker`]s.
+    ///     `MessageTypeDetails::payload.size`.
+    ///     If the `payload.size == 8` a value for number_of_elements of 5 means that there are
+    ///     5 elements of size 8 stored in the [`Sample`].
+    ///  *  When the payload.size == 8 and the number of elements if 5, it means that the sample
+    ///     will contain a slice of 8 * 5 = 40 [`CustomPayloadMarker`]s or 40 bytes.
     #[doc(hidden)]
     pub unsafe fn receive_custom_payload(
         &self,

diff --git a/iceoryx2/src/sample_mut_uninit.rs b/iceoryx2/src/sample_mut_uninit.rs
@@ -114,7 +114,7 @@ use crate::{
 ///
 /// The generic parameter `Payload` is actually [`core::mem::MaybeUninit<Payload>`].
 pub struct SampleMutUninit<Service: crate::service::Service, Payload: Debug + ?Sized, UserHeader> {
-    pub(crate) sample: SampleMut<Service, Payload, UserHeader>,
+    sample: SampleMut<Service, Payload, UserHeader>,
 }
 
 impl<Service: crate::service::Service, Payload: Debug + ?Sized, UserHeader>

diff --git a/iceoryx2/src/service/header/publish_subscribe.rs b/iceoryx2/src/service/header/publish_subscribe.rs
@@ -55,7 +55,15 @@ impl Header {
         self.publisher_port_id
     }
 
-    /// Returns the amount of elements of the payload.
+    /// Returns how many elements are stored inside the sample's payload.
+    ///
+    /// # Details when using
+    /// [`CustomPayloadMarker`](crate::service::builder::publish_subscribe::CustomPayloadMarker)
+    ///
+    /// In this case the number of elements relates to the element defined in the
+    /// [`MessageTypeDetails`](crate::service::static_config::message_type_details::MessageTypeDetails).
+    /// When the element has a `payload.size == 40` and the `Sample::payload().len() == 120` it
+    /// means that it contains 3 elements (3 * 40 == 120).
     pub fn number_of_elements(&self) -> u64 {
         self.number_of_elements
     }