[#264] Add documentation

doc/release-notes/iceoryx2-unreleased.md

@@ -11,6 +11,7 @@
     conflicts when merging.
 -->
 
+* C++ bindings for attributes [#264](https://github.com/eclipse-iceoryx/iceoryx2/issues/264)
 * Add Event-Multiplexer `WaitSet` [#390](https://github.com/eclipse-iceoryx/iceoryx2/issues/390)
 * Add `PeriodicTimer` into POSIX building blocks [#425](https://github.com/eclipse-iceoryx/iceoryx2/issues/425)
 * Developer permissions for resources [#460](https://github.com/eclipse-iceoryx/iceoryx2/issues/460)

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

@@ -17,15 +17,25 @@
 #include "iox2/internal/iceoryx2.hpp"
 
 namespace iox2 {
+/// Represents a single service attribute (key-value) pair that can be defined when the service
+/// is being created.
 class Attribute {
   public:
     using Key = iox::string<IOX2_ATTRIBUTE_KEY_LENGTH>;
     using Value = iox::string<IOX2_ATTRIBUTE_VALUE_LENGTH>;
 };
 
+/// Represents a single view service attribute (key-value) pair that can be defined when the service
+/// is being created.
+///
+/// @attention The parent from which the view was extracted MUST live longer than the
+///            [`AttributeView`].
 class AttributeView {
   public:
+    /// Acquires the service attribute key
     auto key() const -> Attribute::Key;
+
+    /// Acquires the service attribute value
     auto value() const -> Attribute::Value;
 
   private:

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

@@ -20,10 +20,20 @@
 #include <iostream>
 
 namespace iox2 {
+/// Represents all service attributes. They can be set when the service is created.
+///
+/// @attention The parent from which the view was extracted MUST live longer than the
+///            [`AttributeSetView`].
 class AttributeSetView {
   public:
+    /// Returns the number of [`Attribute`]s stored inside the [`AttributeSet`].
     auto len() const -> uint64_t;
+
+    /// Returns a [`AttributeView`] at a specific index. The number of indices is returned via
+    /// [`AttributeSetView::len()`].
     auto at(uint64_t index) const -> AttributeView;
+
+    /// Returns all values to a specific key
     void get_key_values(const Attribute::Key& key,
                         const iox::function<CallbackProgression(const Attribute::Value&)>& callback) const;
 

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

@@ -16,8 +16,12 @@
 #include "attribute_set.hpp"
 
 namespace iox2 {
+
+/// Represents the set of [`Attribute`]s that are defined when the [`Service`]
+/// is created.
 class AttributeSpecifier {
   public:
+    /// Creates a new empty set of [`Attribute`]s
     AttributeSpecifier();
     AttributeSpecifier(const AttributeSpecifier&) = delete;
     AttributeSpecifier(AttributeSpecifier&&) noexcept;
@@ -26,7 +30,10 @@ class AttributeSpecifier {
     auto operator=(const AttributeSpecifier&) -> AttributeSpecifier& = delete;
     auto operator=(AttributeSpecifier&&) noexcept -> AttributeSpecifier&;
 
+    /// Defines a value for a specific key. A key is allowed to have multiple values.
     auto define(const Attribute::Key& key, const Attribute::Value& value) -> AttributeSpecifier&&;
+
+    /// Returns the underlying [`AttributeSetView`]
     auto attributes() const -> AttributeSetView;
 
   private:

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

@@ -20,8 +20,11 @@
 #include "iox2/internal/iceoryx2.hpp"
 
 namespace iox2 {
+/// Represents the set of [`Attribute`]s that are required when the [`Service`]
+/// is opened.
 class AttributeVerifier {
   public:
+    /// Creates a new empty set of [`Attribute`]s
     AttributeVerifier();
     AttributeVerifier(const AttributeVerifier&) = delete;
     AttributeVerifier(AttributeVerifier&&) noexcept;
@@ -30,10 +33,19 @@ class AttributeVerifier {
     auto operator=(const AttributeVerifier&) -> AttributeVerifier& = delete;
     auto operator=(AttributeVerifier&&) noexcept -> AttributeVerifier&;
 
+    /// Requires a value for a specific key. A key is allowed to have multiple values.
     auto require(const Attribute::Key& key, const Attribute::Value& value) -> AttributeVerifier&&;
+
+    /// Requires that a specific key is defined.
     auto require_key(const Attribute::Key& key) -> AttributeVerifier&&;
+
+    /// Returns the underlying required [`AttributeSet`]
     auto attributes() const -> AttributeSetView;
+
+    /// Returns the underlying required keys
     auto keys() const -> iox::vector<Attribute::Key, IOX2_MAX_ATTRIBUTES_PER_SERVICE>;
+
+    /// Verifies if the [`AttributeSet`] contains all required keys and key-value pairs.
     auto verify_requirements(const AttributeSetView& rhs) const -> iox::expected<void, Attribute::Key>;
 
   private:

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

@@ -33,6 +33,11 @@ pub type iox2_attribute_h_ref = *const iox2_attribute_h_t;
 // BEGIN C API
 const ZERO_TERMINATOR_LEN: usize = 1;
 
+/// Returns the length of the attributes key.
+///
+/// # Safety
+///
+/// * The `handle` must be a valid handle.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_key_len(handle: iox2_attribute_h_ref) -> usize {
     debug_assert!(!handle.is_null());
@@ -41,6 +46,13 @@ pub unsafe extern "C" fn iox2_attribute_key_len(handle: iox2_attribute_h_ref) ->
     attribute.key().len() + ZERO_TERMINATOR_LEN
 }
 
+/// Copies the keys value into the provided buffer.
+///
+/// # Safety
+///
+/// * `handle` - A valid [`iox2_attribute_h_ref`],
+/// * `buffer` - Must be non-null and pointing to a valid memory location,
+/// * `buffer_len` - Must be the length of the provided `buffer`.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_key(
     handle: iox2_attribute_h_ref,
@@ -63,6 +75,11 @@ pub unsafe extern "C" fn iox2_attribute_key(
     }
 }
 
+/// Returns the length of the attributes value.
+///
+/// # Safety
+///
+/// * The `handle` must be a valid handle.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_value_len(handle: iox2_attribute_h_ref) -> usize {
     debug_assert!(!handle.is_null());
@@ -71,6 +88,13 @@ pub unsafe extern "C" fn iox2_attribute_value_len(handle: iox2_attribute_h_ref)
     attribute.value().len() + ZERO_TERMINATOR_LEN
 }
 
+/// Copies the values value into the provided buffer.
+///
+/// # Safety
+///
+/// * `handle` - A valid [`iox2_attribute_h_ref`],
+/// * `buffer` - Must be non-null and pointing to a valid memory location,
+/// * `buffer_len` - Must be the length of the provided `buffer`.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_value(
     handle: iox2_attribute_h_ref,
@@ -92,5 +116,4 @@ pub unsafe extern "C" fn iox2_attribute_value(
         0
     }
 }
-
 // END C API

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

@@ -36,6 +36,12 @@ pub type iox2_attribute_set_get_callback =
 // END type definition
 
 // BEGIN C API
+
+/// Returns the length of the attribute set.
+///
+/// # Safety
+///
+/// * The `handle` must be a valid handle.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_set_len(handle: iox2_attribute_set_h_ref) -> usize {
     debug_assert!(!handle.is_null());
@@ -44,6 +50,12 @@ pub unsafe extern "C" fn iox2_attribute_set_len(handle: iox2_attribute_set_h_ref
     attribute_set.iter().len()
 }
 
+/// Returns a [`iox2_attribute_h_ref`] to the attribute stored at the provided index.
+///
+/// # Safety
+///
+/// * The `handle` must be a valid handle.
+/// * The `index` < [`iox2_attribute_set_len()`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_set_at(
     handle: iox2_attribute_set_h_ref,
@@ -56,6 +68,13 @@ pub unsafe extern "C" fn iox2_attribute_set_at(
     (&attribute_set[index] as *const Attribute).cast()
 }
 
+/// Calls the provided callback for every value that is owned by the provided key.
+///
+/// # Safety
+///
+/// * The `handle` must be a valid handle.
+/// * The `key` must be a valid null-terminated string.
+/// * The `callback` must point to a function with the required signature.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_set_get_key_values(
     handle: iox2_attribute_set_h_ref,

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

@@ -102,6 +102,13 @@ impl HandleToType for iox2_attribute_specifier_h_ref {
 
 // BEGIN C API
 
+/// Creates a new [`iox2_attribute_specifier_h`]. It must be cleaned up with
+/// [`iox2_attribute_specifier_drop()`].
+/// If the `struct_ptr` is null, then the function will allocate memory.
+///
+/// # Safety
+///
+/// * The `handle_ptr` must point to an uninitialized [`iox2_attribute_specifier_h`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_specifier_new(
     struct_ptr: *mut iox2_attribute_specifier_t,
@@ -128,6 +135,12 @@ pub unsafe extern "C" fn iox2_attribute_specifier_new(
     IOX2_OK
 }
 
+/// Deletes a [`iox2_attribute_specifier_h`]. It must be created with
+/// [`iox2_attribute_specifier_new()`].
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_specifier_h`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_specifier_drop(handle: iox2_attribute_specifier_h) {
     debug_assert!(!handle.is_null());
@@ -138,6 +151,13 @@ pub unsafe extern "C" fn iox2_attribute_specifier_drop(handle: iox2_attribute_sp
     (attribute_specifier.deleter)(attribute_specifier);
 }
 
+/// Defines a attribute (key / value pair).
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_specifier_h`].
+/// * The `key` must point to a valid null-terminated string.
+/// * The `value` must point to a valid null-terminated string.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_specifier_define(
     handle: iox2_attribute_specifier_h_ref,
@@ -160,6 +180,12 @@ pub unsafe extern "C" fn iox2_attribute_specifier_define(
     ));
 }
 
+/// Returnes a [`iox2_attribute_set_h_ref`] to the underlying attribute set.
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_specifier_h`].
+/// * The `handle` must live at least as long as the returned [`iox2_attribute_set_h_ref`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_specifier_attributes(
     handle: iox2_attribute_specifier_h_ref,

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

@@ -102,6 +102,13 @@ impl HandleToType for iox2_attribute_verifier_h_ref {
 
 // BEGIN C API
 
+/// Creates a new [`iox2_attribute_verifier_h`]. It must be cleaned up with
+/// [`iox2_attribute_verifier_drop()`].
+/// If the `struct_ptr` is null, then the function will allocate memory.
+///
+/// # Safety
+///
+/// * The `handle_ptr` must point to an uninitialized [`iox2_attribute_verifier_h`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_new(
     struct_ptr: *mut iox2_attribute_verifier_t,
@@ -128,6 +135,12 @@ pub unsafe extern "C" fn iox2_attribute_verifier_new(
     IOX2_OK
 }
 
+/// Deletes a [`iox2_attribute_verifier_h`]. It must be created with
+/// [`iox2_attribute_verifier_new()`].
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_drop(handle: iox2_attribute_verifier_h) {
     debug_assert!(!handle.is_null());
@@ -138,6 +151,13 @@ pub unsafe extern "C" fn iox2_attribute_verifier_drop(handle: iox2_attribute_ver
     (attribute_verifier.deleter)(attribute_verifier);
 }
 
+/// Defines a attribute (key / value pair) that is required.
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`].
+/// * The `key` must point to a valid null-terminated string.
+/// * The `value` must point to a valid null-terminated string.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_require(
     handle: iox2_attribute_verifier_h_ref,
@@ -160,6 +180,12 @@ pub unsafe extern "C" fn iox2_attribute_verifier_require(
     ));
 }
 
+/// Defines a key that must be present.
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`].
+/// * The `key` must point to a valid null-terminated string.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_require_key(
     handle: iox2_attribute_verifier_h_ref,
@@ -179,6 +205,12 @@ pub unsafe extern "C" fn iox2_attribute_verifier_require_key(
     ));
 }
 
+/// Returnes a [`iox2_attribute_set_h_ref`] to the underlying attribute set.
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`].
+/// * The `handle` must live at least as long as the returned [`iox2_attribute_set_h_ref`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_attributes(
     handle: iox2_attribute_verifier_h_ref,
@@ -189,6 +221,14 @@ pub unsafe extern "C" fn iox2_attribute_verifier_attributes(
     (attribute_verifier_struct.value.as_ref().0.attributes() as *const AttributeSet).cast()
 }
 
+/// Verifies if the [`iox2_attribute_set_h_ref`] contains all required keys and key-value pairs.
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`].
+/// * The `rhs` must be valid.
+/// * `incompatible_key_buffer` must be either null or point to a valid memory location of size
+///   `incompatible_key_buffer_len`
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_verify_requirements(
     handle: iox2_attribute_verifier_h_ref,
@@ -219,6 +259,11 @@ pub unsafe extern "C" fn iox2_attribute_verifier_verify_requirements(
     }
 }
 
+/// Returns the number of required keys.
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`].
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_number_of_keys(
     handle: iox2_attribute_verifier_h_ref,
@@ -229,6 +274,12 @@ pub unsafe extern "C" fn iox2_attribute_verifier_number_of_keys(
     attribute_verifier.keys().len()
 }
 
+/// Returns the length of a required key at a specific key index.
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`].
+/// * `key_index` < [`iox2_attribute_verifier_number_of_keys()`]
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_key_len(
     handle: iox2_attribute_verifier_h_ref,
@@ -242,6 +293,13 @@ pub unsafe extern "C" fn iox2_attribute_verifier_key_len(
     attribute_verifier.keys()[key_index].len()
 }
 
+/// Copies the key value at a specific key index into the provided buffer.
+///
+/// # Safety
+///
+/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`].
+/// * `key_index` < [`iox2_attribute_verifier_number_of_keys()`]
+/// * `key_value_buffer` must point to a valid memory location of size `key_value_buffer_len`.
 #[no_mangle]
 pub unsafe extern "C" fn iox2_attribute_verifier_key(
     handle: iox2_attribute_verifier_h_ref,
@@ -270,5 +328,4 @@ pub unsafe extern "C" fn iox2_attribute_verifier_key(
         0
     }
 }
-
 // END C API