iox-eclipse-iceoryx#751 Add doxygen docu

Signed-off-by: Christian Eltzschig <me@elchris.org>

iceoryx_hoofs/include/iceoryx_hoofs/internal/posix_wrapper/semaphore_interface.hpp

@@ -26,12 +26,17 @@ namespace posix
 {
 namespace internal
 {
+/// @brief Represent the state of a semaphore
 struct SemaphoreState
 {
+    /// @brief current value of the semaphore
     uint32_t value = 0U;
+
+    /// @brief states the number of threads waiting in wait, or timedWait
     uint32_t numberOfBlockedWait = 0U;
 };
 
+/// @brief Defines the interface of a named and unnamed semaphore.
 template <typename SemaphoreChild>
 class SemaphoreInterface
 {
@@ -42,10 +47,30 @@ class SemaphoreInterface
     SemaphoreInterface& operator=(SemaphoreInterface&&) noexcept = delete;
     ~SemaphoreInterface() noexcept = default;
 
+    /// @brief Increments the semaphore by one
+    /// @return Fails when the value of the semaphore overflows or when the
+    ///         semaphore was removed from outside the process
     cxx::expected<SemaphoreError> post() noexcept;
+
+    /// @brief Returns the state of the semaphore
+    /// @return Fails when semaphore was removed from outside the process
     cxx::expected<SemaphoreState, SemaphoreError> getState() noexcept;
+
+    /// @brief Decrements the semaphore by one. When the semaphore value is zero
+    ///        it blocks until the semaphore value is greater zero
+    /// @return Fails when semaphore was removed from outside the process
     cxx::expected<SemaphoreError> wait() noexcept;
+
+    /// @brief Tries to decrement the semaphore by one. When the semaphore value is zero
+    ///        it returns false otherwise it returns true and decrement the value by one.
+    /// @return Fails when semaphore was removed from outside the process
     cxx::expected<bool, SemaphoreError> tryWait() noexcept;
+
+    /// @brief Tries to decrement the semaphore by one. When the semaphore value is zero
+    ///        it waits until the timeout has passed.
+    /// @return If during the timeout time the semaphore value increases to non zero
+    ///         it returns SemaphoreWaitState::NO_TIMEOUT and decreases the semaphore by one
+    ///         otherwise returns SemaphoreWaitState::TIMEOUT
     cxx::expected<SemaphoreWaitState, SemaphoreError> timedWait(const units::Duration& timeout) noexcept;
 
   protected:

iceoryx_hoofs/include/iceoryx_hoofs/posix_wrapper/unnamed_semaphore.hpp

@@ -25,6 +25,7 @@ namespace iox
 {
 namespace posix
 {
+/// @brief A unnamed posix semaphore.
 class UnnamedSemaphore final : public internal::SemaphoreInterface<UnnamedSemaphore>
 {
   public:
@@ -48,7 +49,11 @@ class UnnamedSemaphore final : public internal::SemaphoreInterface<UnnamedSemaph
 
 class UnnamedSemaphoreBuilder
 {
+    /// @brief Set the initial value of the unnamed posix semaphore
     IOX_BUILDER_PARAMETER(uint32_t, initialValue, 0U)
+
+    /// @brief Set if the unnamed semaphore can be stored in the shared memory
+    ///        for inter process usage
     IOX_BUILDER_PARAMETER(bool, isInterProcessCapable, true)
 
   public:

iceoryx_hoofs/source/posix_wrapper/semaphore_interface.cpp

@@ -25,7 +25,6 @@ namespace posix
 {
 namespace internal
 {
-
 template <typename SemaphoreChild>
 iox_sem_t* SemaphoreInterface<SemaphoreChild>::getHandle() noexcept
 {
@@ -164,7 +163,6 @@ cxx::expected<SemaphoreError> SemaphoreInterface<SemaphoreChild>::wait() noexcep
     return cxx::success<>();
 }
 
-
 template class SemaphoreInterface<UnnamedSemaphore>;
 } // namespace internal
 } // namespace posix

iceoryx_hoofs/test/moduletests/test_posix_unnamed_semaphore.cpp

@@ -53,4 +53,3 @@ TEST_F(UnnamedSemaphoreTest, InitialValueIsSetOnCreation)
     }
 }
 } // namespace
-