[#264] Add documentation and fix clippy warnings

iceoryx2-ffi/cxx/include/iox2/node_failure_enums.hpp

@@ -36,6 +36,8 @@ enum class NodeCreationFailure : uint8_t {
     InternalError
 };
 
+/// Failures of [`DeadNodeView::remove_stale_resources()`] that occur when the stale resources of
+/// a dead [`Node`] are removed.
 enum class NodeCleanupFailure : uint8_t {
     /// The process received an interrupt signal while cleaning up all stale resources of a dead [`Node`].
     Interrupt,

iceoryx2-ffi/cxx/include/iox2/node_id.hpp

@@ -21,6 +21,7 @@
 #include <iostream>
 
 namespace iox2 {
+/// The system-wide unique id of a [`Node`]
 class NodeId {
   public:
     NodeId(const NodeId& rhs);
@@ -29,10 +30,10 @@ class NodeId {
     auto operator=(NodeId&& rhs) noexcept -> NodeId&;
     ~NodeId();
 
-    /// Returns high bits of the underlying value of the [`NodeId`].
+    /// Returns the high bits of the underlying value of the [`NodeId`].
     auto value_high() const -> uint64_t;
 
-    /// Returns low bits of the underlying value of the [`NodeId`].
+    /// Returns the low bits of the underlying value of the [`NodeId`].
     auto value_low() const -> uint64_t;
 
     /// Returns the [`ProcessId`] of the process that owns the [`Node`].
@@ -47,12 +48,9 @@ class NodeId {
     template <ServiceType>
     friend class DeadNodeView;
     template <ServiceType>
-    friend auto list_callback(iox2_node_state_e,
-                              iox2_node_id_ptr,
-                              const char*,
-                              iox2_node_name_ptr,
-                              iox2_config_ptr,
-                              iox2_callback_context) -> iox2_callback_progression_e;
+    friend auto list_callback(
+        iox2_node_state_e, iox2_node_id_ptr, const char*, iox2_node_name_ptr, iox2_config_ptr, iox2_callback_context)
+        -> iox2_callback_progression_e;
 
 
     explicit NodeId(iox2_node_id_h handle);

iceoryx2-ffi/cxx/include/iox2/node_state.hpp

@@ -103,12 +103,9 @@ class NodeState {
   private:
     template <ServiceType>
     // NOLINTBEGIN(readability-function-size)
-    friend auto list_callback(iox2_node_state_e,
-                              iox2_node_id_ptr,
-                              const char*,
-                              iox2_node_name_ptr,
-                              iox2_config_ptr,
-                              iox2_callback_context) -> iox2_callback_progression_e;
+    friend auto list_callback(
+        iox2_node_state_e, iox2_node_id_ptr, const char*, iox2_node_name_ptr, iox2_config_ptr, iox2_callback_context)
+        -> iox2_callback_progression_e;
 
     explicit NodeState(const AliveNodeView<T>& view);
     explicit NodeState(const DeadNodeView<T>& view);

iceoryx2-ffi/ffi/src/api/node.rs

@@ -37,11 +37,15 @@ use super::{iox2_config_h_ref, iox2_node_id_h_ref, iox2_node_id_ptr, iox2_signal
 
 // BEGIN type definition
 
+/// The failures that can occur when a list of node states is created with [`iox2_node_list()`].
 #[repr(C)]
 #[derive(Copy, Clone, StringLiteral)]
 pub enum iox2_node_list_failure_e {
+    /// A list of all Nodes could not be created since the process does not have sufficient permissions.
     INSUFFICIENT_PERMISSIONS = IOX2_OK as isize + 1,
+    /// The process received an interrupt signal while acquiring the list of all Nodes.
     INTERRUPT,
+    /// Errors that indicate either an implementation issue or a wrongly configured system.
     INTERNAL_ERROR,
 }
 
@@ -73,11 +77,16 @@ impl IntoCInt for NodeWaitFailure {
     }
 }
 
+/// Failures of [`iox2_dead_node_remove_stale_resources()`] that occur when the stale resources of
+/// a dead node are removed.
 #[repr(C)]
 #[derive(Copy, Clone, StringLiteral)]
 pub enum iox2_node_cleanup_failure_e {
+    /// The process received an interrupt signal while cleaning up all stale resources of a dead node.
     INTERRUPT = IOX2_OK as isize + 1,
+    /// Errors that indicate either an implementation issue or a wrongly configured system.
     INTERNAL_ERROR,
+    /// The stale resources of a dead node could not be removed since the process does not have sufficient permissions.
     INSUFFICIENT_PERMISSIONS,
 }
 
@@ -348,15 +357,29 @@ pub unsafe extern "C" fn iox2_node_id(
     }
 }
 
+/// Removes all stale resources of a dead node under a provided config.
+///
+/// Returns [`IOX2_OK`] on success, otherwise [`iox2_node_cleanup_failure_e`].
+///
+/// # Safety
+///
+/// * The `node_handle` must be valid and obtained by [`iox2_node_builder_create`](crate::iox2_node_builder_create)!
+/// * The `node_id` must be valid
+/// * The `config` must be valid
+/// * `has_success` must point to a valid memory location
 #[no_mangle]
 pub unsafe extern "C" fn iox2_dead_node_remove_stale_resources(
     service_type: iox2_service_type_e,
     node_id: iox2_node_id_h_ref,
     config: iox2_config_h_ref,
     has_success: *mut bool,
 ) -> c_int {
-    let node_id = (&*node_id.as_type()).value.as_ref();
-    let config = (&*config.as_type()).value.as_ref();
+    node_id.assert_non_null();
+    config.assert_non_null();
+    debug_assert!(!has_success.is_null());
+
+    let node_id = (*node_id.as_type()).value.as_ref();
+    let config = (*config.as_type()).value.as_ref();
 
     let result = match service_type {
         iox2_service_type_e::IPC => {

iceoryx2-ffi/ffi/src/api/node_id.rs

@@ -80,6 +80,15 @@ impl HandleToType for iox2_node_id_h_ref {
 // END type definition
 
 // BEGIN C API
+
+/// Creates a new [`iox2_node_id_h`] by cloning a [`iox2_node_id_ptr`].
+///
+/// # Safety
+///
+/// * `node_id_struct_ptr` - Must be either a NULL pointer or a pointer to a valid [`iox2_node_id_t`].
+///   If it is a NULL pointer, the storage will be allocated on the heap.
+/// * `node_id_ptr` - Must be a valid [`iox2_node_id_ptr`]
+/// * `node_id_handle_ptr` - Must point to a valid [`iox2_node_id_h`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_id_clone_from_ptr(
     node_id_struct_ptr: *mut iox2_node_id_t,
@@ -104,10 +113,18 @@ pub unsafe extern "C" fn iox2_node_id_clone_from_ptr(
         (*node_id_struct_ptr).deleter = deleter;
     }
 
-    (*node_id_struct_ptr).value.init((*node_id_ptr).clone());
+    (*node_id_struct_ptr).value.init(*node_id_ptr);
     *node_id_handle_ptr = (*node_id_struct_ptr).as_handle();
 }
 
+/// Creates a new [`iox2_node_id_h`] by cloning a [`iox2_node_id_h_ref`].
+///
+/// # Safety
+///
+/// * `node_id_struct_ptr` - Must be either a NULL pointer or a pointer to a valid [`iox2_node_id_t`].
+///   If it is a NULL pointer, the storage will be allocated on the heap.
+/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`]
+/// * `node_id_handle_ptr` - Must point to a valid [`iox2_node_id_h`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_id_clone_from_handle(
     node_id_struct_ptr: *mut iox2_node_id_t,
@@ -123,6 +140,11 @@ pub unsafe extern "C" fn iox2_node_id_clone_from_handle(
     iox2_node_id_clone_from_ptr(node_id_struct_ptr, node_id_ptr, node_id_handle_ptr);
 }
 
+/// Returns the high bits of the underlying value of the [`iox2_node_id_h`].
+///
+/// # Safety
+///
+/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`]
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_id_value_high(node_id_handle: iox2_node_id_h_ref) -> u64 {
     node_id_handle.assert_non_null();
@@ -131,6 +153,11 @@ pub unsafe extern "C" fn iox2_node_id_value_high(node_id_handle: iox2_node_id_h_
     (node_id.value.as_ref().value() >> 64) as u64
 }
 
+/// Returns the low bits of the underlying value of the [`iox2_node_id_h`].
+///
+/// # Safety
+///
+/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`]
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_id_value_low(node_id_handle: iox2_node_id_h_ref) -> u64 {
     node_id_handle.assert_non_null();
@@ -139,6 +166,11 @@ pub unsafe extern "C" fn iox2_node_id_value_low(node_id_handle: iox2_node_id_h_r
     ((node_id.value.as_ref().value() << 64) >> 64) as u64
 }
 
+/// Returns the process id of the [`iox2_node_id_h`].
+///
+/// # Safety
+///
+/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`]
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_id_pid(node_id_handle: iox2_node_id_h_ref) -> i32 {
     node_id_handle.assert_non_null();
@@ -147,6 +179,13 @@ pub unsafe extern "C" fn iox2_node_id_pid(node_id_handle: iox2_node_id_h_ref) ->
     node_id.value.as_ref().pid().value()
 }
 
+/// Returns the creation time of the [`iox2_node_id_h`].
+///
+/// # Safety
+///
+/// * `node_id_handle` - Must be a valid [`iox2_node_id_h_ref`]
+/// * `seconds` - Must point to a valid memory location
+/// * `nanoseconds` - Must point to a valid memory location
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_id_creation_time(
     node_id_handle: iox2_node_id_h_ref,
@@ -162,6 +201,12 @@ pub unsafe extern "C" fn iox2_node_id_creation_time(
     *nanoseconds = node_id.value.as_ref().creation_time().nanoseconds();
 }
 
+/// Takes ownership of the handle to delete and remove the underlying resources of a
+/// [`iox2_node_id_h`].
+///
+/// # Safety
+///
+/// * `node_id_handle` - Must be a valid [`iox2_node_id_h`]
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_id_drop(node_id_handle: iox2_node_id_h) {
     debug_assert!(!node_id_handle.is_null());