[eclipse-iceoryx#491] Document new C functions

iceoryx2-ffi/cxx/src/error_string.cpp

@@ -132,8 +132,4 @@ auto error_string(const iox2::WaitSetRunError& error) -> const char* {
     return iox2_waitset_run_error_string(iox::into<iox2_waitset_run_error_e>(error));
 }
 
-auto error_string(const iox2::WaitSetRunResult& error) -> const char* {
-    return iox2_waitset_run_result_string(iox::into<iox2_waitset_run_result_e>(error));
-}
-
 } // namespace iox2

iceoryx2-ffi/cxx/tests/src/error_string_tests.cpp

@@ -257,14 +257,6 @@ TEST(ErrorStringTest, waitset_create_error_string) {
     ASSERT_GT(strlen(error_string(Sut::InternalError)), 1U);
 }
 
-TEST(ErrorStringTest, waitset_run_result_string) {
-    using Sut = iox2::WaitSetRunResult;
-    ASSERT_GT(strlen(error_string(Sut::TerminationRequest)), 1U);
-    ASSERT_GT(strlen(error_string(Sut::Interrupt)), 1U);
-    ASSERT_GT(strlen(error_string(Sut::StopRequest)), 1U);
-    ASSERT_GT(strlen(error_string(Sut::AllEventsHandled)), 1U);
-}
-
 TEST(ErrorStringTest, waitset_attachment_error_string) {
     using Sut = iox2::WaitSetAttachmentError;
     ASSERT_GT(strlen(error_string(Sut::InsufficientCapacity)), 1U);

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

@@ -136,6 +136,20 @@ impl HandleToType for iox2_config_h_ref {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_config_creation_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_config_creation_error_string(
     error: iox2_config_creation_error_e,

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

@@ -140,6 +140,20 @@ pub type iox2_listener_wait_all_callback =
 
 // BEGIN C API
 
+/// Returns a string representation of the provided [`iox2_listener_wait_error_e`] error code.
+///
+/// # Arguments
+///
+/// * `error` - The error code that should be converted into a string
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// * The returned pointer must not be modified or freed and is only valid as long as the program runs
 #[no_mangle]
 pub unsafe extern "C" fn iox2_listener_wait_error_string(
     error: iox2_listener_wait_error_e,

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

@@ -189,6 +189,20 @@ trait AssertNonNullHandle {
     fn assert_non_null(self);
 }
 
+/// Returns a string literal describing the provided [`iox2_semantic_string_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_semantic_string_error_string(
     error: iox2_semantic_string_error_e,

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

@@ -187,13 +187,38 @@ pub type iox2_node_list_callback = extern "C" fn(
 
 // BEGIN C API
 
+/// Returns a string representation of the [`iox2_node_list_failure_e`] error code.
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// Returns a pointer to a null-terminated string containing the error description.
+///
+/// # Safety
+///
+/// * The returned pointer is valid as long as the program runs and must not be modified or freed
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_list_failure_string(
     error: iox2_node_list_failure_e,
 ) -> *const c_char {
     error.as_str_literal().as_ptr() as *const c_char
 }
 
+/// Returns a string representation of the [`iox2_node_wait_failure_e`] error code.
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// * The returned pointer is valid as long as the program runs and must not be modified or freed
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_wait_failure_string(
     error: iox2_node_wait_failure_e,

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

@@ -101,6 +101,20 @@ impl HandleToType for iox2_node_builder_h_ref {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_node_creation_failure_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_node_creation_failure_string(
     error: iox2_node_creation_failure_e,

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

@@ -131,6 +131,20 @@ impl HandleToType for iox2_notifier_h_ref {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_notifier_notify_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_notifier_notify_error_string(
     error: iox2_notifier_notify_error_e,

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

@@ -136,6 +136,20 @@ impl HandleToType for iox2_port_factory_listener_builder_h_ref {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_listener_create_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_listener_create_error_string(
     error: iox2_listener_create_error_e,

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

@@ -132,6 +132,20 @@ impl HandleToType for iox2_port_factory_notifier_builder_h_ref {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_notifier_create_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_notifier_create_error_string(
     error: iox2_notifier_create_error_e,

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

@@ -175,6 +175,20 @@ impl HandleToType for iox2_port_factory_publisher_builder_h_ref {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_publisher_create_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_publisher_create_error_string(
     error: iox2_publisher_create_error_e,

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

@@ -140,6 +140,20 @@ impl HandleToType for iox2_port_factory_subscriber_builder_h_ref {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_subscriber_create_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_subscriber_create_error_string(
     error: iox2_subscriber_create_error_e,

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

@@ -246,13 +246,41 @@ unsafe fn send_slice_copy<S: Service>(
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_publisher_send_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_publisher_send_error_string(
     error: iox2_publisher_send_error_e,
 ) -> *const c_char {
     error.as_str_literal().as_ptr() as *const c_char
 }
 
+/// Returns a string literal describing the provided [`iox2_publisher_loan_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_publisher_loan_error_string(
     error: iox2_publisher_loan_error_e,

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

@@ -134,13 +134,41 @@ pub type iox2_service_list_callback = extern "C" fn(
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_service_details_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_service_details_error_string(
     error: iox2_service_details_error_e,
 ) -> *const c_char {
     error.as_str_literal().as_ptr() as *const c_char
 }
 
+/// Returns a string literal describing the provided [`iox2_service_list_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_service_list_error_string(
     error: iox2_service_list_error_e,

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

@@ -157,6 +157,20 @@ impl IntoCInt for EventOpenOrCreateError {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_event_open_or_create_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_event_open_or_create_error_string(
     error: iox2_event_open_or_create_error_e,

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

@@ -227,6 +227,20 @@ pub enum iox2_type_detail_error_e {
 
 // BEGIN C API
 
+/// Returns a string literal describing the provided [`iox2_pub_sub_open_or_create_error_e`].
+///
+/// # Arguments
+///
+/// * `error` - The error value for which a description should be returned
+///
+/// # Returns
+///
+/// A pointer to a null-terminated string containing the error message.
+/// The string is stored in the .rodata section of the binary.
+///
+/// # Safety
+///
+/// The returned pointer must not be modified or freed and is valid as long as the program runs.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_pub_sub_open_or_create_error_string(
     error: iox2_pub_sub_open_or_create_error_e,