iox-eclipse-iceoryx#605 fix doxygen comments

Signed-off-by: Marika Lehmann <[email protected]>

doc/conceptual-guide.md

@@ -143,7 +143,7 @@ Memory chunks are returned to the pool once all attached `SubscriberPort`s indic
 As already discussed, shared memory segments may be mapped to different memory areas in the virtual address space of a
 process.
 To deal with this, iceoryx utilizes specialized pointer types: the `iox::rp::RelativePointer` and
-the `iox::RelocatablePointer`.
+the `iox::rp::RelocatablePointer`.
 
 Using these types, the difference in memory mapping is not a factor when it comes to locating a memory chunk.
 

iceoryx_utils/include/iceoryx_utils/internal/relocatable_pointer/atomic_relocatable_ptr.hpp

@@ -37,8 +37,8 @@ class atomic_relocatable_ptr
     using offset_t = std::ptrdiff_t;
     static constexpr offset_t NULL_POINTER_OFFSET = std::numeric_limits<offset_t>::max();
 
-    /// @brief creates atomic_relocatable_ptr pointing to ptr
-    /// @param[in] ptr pointee
+    /// @brief creates an atomic_relocatable_ptr pointing to the same pointee as ptr
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     atomic_relocatable_ptr(const T* ptr = nullptr) noexcept;
 
     /// @todo: can be implemented when needed, note that the offset must be recomputed during the move/copy
@@ -49,8 +49,8 @@ class atomic_relocatable_ptr
 
     /// @note minimal set of required operators, can be extended later
 
-    /// @brief assign atomic_relocatable_ptr to point to ptr
-    /// @param[in] ptr pointee
+    /// @brief assign atomic_relocatable_ptr to point to the same pointee as ptr
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     /// @return reference to self
     atomic_relocatable_ptr& operator=(const T* ptr) noexcept;
 

iceoryx_utils/include/iceoryx_utils/internal/relocatable_pointer/base_relative_ptr.hpp

@@ -56,8 +56,8 @@ class BaseRelativePointer
     using const_ptr_t = const void* const;
     using offset_t = std::uintptr_t;
 
-    /// @brief constructs a BaseRelativePointer pointing to ptr in a segment identified by id
-    /// @param[in] ptr is the pointee
+    /// @brief constructs a BaseRelativePointer pointing to the same pointee as ptr in a segment identified by id
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     /// @param[in] id is the unique id of the segment
     BaseRelativePointer(ptr_t ptr, id_t id) noexcept;
 
@@ -66,8 +66,8 @@ class BaseRelativePointer
     /// @param[in] id is the unique id of the segment
     BaseRelativePointer(offset_t offset, id_t id) noexcept;
 
-    /// @brief constructs a BaseRelativePointer pointing to ptr
-    /// @param[in] ptr is the pointee
+    /// @brief constructs a BaseRelativePointer pointing to the same pointer as ptr
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     BaseRelativePointer(ptr_t ptr = nullptr) noexcept;
 
     /// @brief copy constructor
@@ -83,8 +83,8 @@ class BaseRelativePointer
     /// @return a reference to self
     BaseRelativePointer& operator=(const BaseRelativePointer& other) noexcept;
 
-    /// @brief assigns the BaseRelativePointer to point to ptr
-    /// @param[in] ptr is the pointee
+    /// @brief assigns the BaseRelativePointer to point to the same pointee as ptr
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     /// @return reference to self
     BaseRelativePointer& operator=(void* ptr) noexcept;
 
@@ -94,7 +94,7 @@ class BaseRelativePointer
     BaseRelativePointer& operator=(BaseRelativePointer&& other) noexcept;
 
     /// @brief access to the underlying object
-    /// @return a poiter to the underlying object
+    /// @return a pointer to the underlying object
     ptr_t get() const noexcept;
 
     /// @brief returns the id which identifies the segment
@@ -115,7 +115,7 @@ class BaseRelativePointer
     /// @return id it was registered to
     static id_t registerPtr(const ptr_t ptr, uint64_t size = 0U) noexcept;
 
-    /// @brief registers a memory segment at ptr with size of given id
+    /// @brief tries to register a memory segment with a given size starting at ptr to a given id
     /// @param[in] id is the id of the segment
     /// @param[in] ptr starting address of the segment to be registered
     /// @param[in] size is the size of the segment
@@ -136,7 +136,7 @@ class BaseRelativePointer
     static void unregisterAll() noexcept;
 
     /// @brief get the offset from id and ptr
-    /// @param[in] id is the id of the segment and is used to get the bease pointer
+    /// @param[in] id is the id of the segment and is used to get the base pointer
     /// @param[in] ptr is the pointer whose offset should be calculated
     /// @return offset
     static offset_t getOffset(const id_t id, const_ptr_t ptr) noexcept;

iceoryx_utils/include/iceoryx_utils/internal/relocatable_pointer/base_relocatable_ptr.hpp

@@ -51,8 +51,8 @@ class BaseRelocatablePointer
     /// @brief default constructs a logical nullptr
     BaseRelocatablePointer() noexcept;
 
-    /// @brief creates a relocatable pointer pointing to ptr
-    /// @param[in] ptr pointee
+    /// @brief creates a relocatable pointer pointing to the same pointee as ptr
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     explicit BaseRelocatablePointer(const void* ptr) noexcept;
 
     /// @brief copy constructor
@@ -68,8 +68,8 @@ class BaseRelocatablePointer
     /// @return reference to self
     BaseRelocatablePointer& operator=(const BaseRelocatablePointer& other) noexcept;
 
-    /// @brief assign BaseRelocatablePointer to point to rawPtr
-    /// @param[in] rawPtr pointee
+    /// @brief assign BaseRelocatablePointer to point to the same pointee as rawPtr
+    /// @param[in] rawPtr the pointer whose pointee shall be the same for this
     /// @return reference to self
     BaseRelocatablePointer& operator=(const void* rawPtr) noexcept;
 

iceoryx_utils/include/iceoryx_utils/internal/relocatable_pointer/pointer_repository.hpp

@@ -75,7 +75,7 @@ class PointerRepository
     /// @brief unregisters all ids and also invalidates all relative pointers
     void unregisterAll() noexcept;
 
-    /// @brief gets the base pointer associated with id
+    /// @brief gets the base pointer, i.e. the starting address, associated with id
     /// @param[in] id is the segment id
     /// @return the base pointer associated with the id
     ptr_t getBasePtr(id_t id) const noexcept;

iceoryx_utils/include/iceoryx_utils/internal/relocatable_pointer/relative_ptr.hpp

@@ -33,8 +33,8 @@ template <typename T>
 class RelativePointer : public BaseRelativePointer
 {
   public:
-    /// @brief constructs a RelativePointer pointing to ptr in a segment identified by id
-    /// @param[in] ptr is the pointee
+    /// @brief constructs a RelativePointer pointing to the same pointee as ptr in a segment identified by id
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     /// @param[in] id is the unique id of the segment
     RelativePointer(ptr_t ptr, id_t id) noexcept;
 
@@ -43,21 +43,21 @@ class RelativePointer : public BaseRelativePointer
     /// @param[in] id is the unique id of the segment
     RelativePointer(offset_t offset, id_t id) noexcept;
 
-    /// @brief constructs a RelativePointer pointing to ptr
-    /// @param[in] ptr is the pointee
+    /// @brief constructs a RelativePointer pointing to the same pointee as ptr
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     RelativePointer(ptr_t ptr = nullptr) noexcept;
 
     /// @brief creates a RelativePointer from a BaseRelativePointer
     /// @param[in] other is the BaseRelativePointer
     RelativePointer(const BaseRelativePointer& other) noexcept;
 
-    /// @brief assign this to point to the BaseRelativePointer other
-    /// @param[in] other is the pointee
+    /// @brief assign this to point to the same pointee as the BaseRelativePointer other
+    /// @param[in] other the pointer whose pointee shall be the same for this
     /// @return reference to self
     RelativePointer& operator=(const BaseRelativePointer& other) noexcept;
 
-    /// @brief assigns the RelativePointer to point to ptr
-    /// @param[in] ptr is the pointee
+    /// @brief assigns the RelativePointer to point to the same pointee as ptr
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     /// @return reference to self
     RelativePointer& operator=(ptr_t ptr) noexcept;
 
@@ -89,14 +89,14 @@ class RelativePointer : public BaseRelativePointer
     /// @return a pointer of type T pointing to the underlying object
     operator T*() const noexcept;
 
-    /// @brief checks if the raw pointer is equal to ptr
-    /// @param[in] ptr is the pointer to be compared with the raw pointer
-    /// @return true if ptr is equal to the raw pointer, otherwise false
+    /// @brief checks if this and ptr point to the same pointee
+    /// @param[in] ptr is the pointer whose pointee is compared with this' pointee
+    /// @return true if the pointees are equal, otherwise false
     bool operator==(T* const ptr) const noexcept;
 
-    /// @brief checks if the raw pointer is not equal to ptr
-    /// @param[in] ptr is the pointer to be compared with the raw pointer
-    /// @return true if ptr is not equal to the raw pointer, otherwise false
+    /// @brief checks if this and ptr point not to the same pointee
+    /// @param[in] ptr is the pointer whose pointee is compared with this' pointee
+    /// @return true if the pointees are not equal, otherwise false
     bool operator!=(T* const ptr) const noexcept;
 };
 

iceoryx_utils/include/iceoryx_utils/internal/relocatable_pointer/relocatable_ptr.hpp

@@ -32,20 +32,20 @@ class RelocatablePointer : public BaseRelocatablePointer
     /// @brief default constructs a logical nullptr
     RelocatablePointer() noexcept;
 
-    /// @brief creates a RelocatablePointer pointing to ptr
-    /// @param[in] ptr is the pointee
+    /// @brief creates a RelocatablePointer pointing to the same pointee as ptr
+    /// @param[in] ptr the pointer whose pointee shall be the same for this
     RelocatablePointer(const T* ptr) noexcept;
 
     /// @brief creates a RelocatablePointer from a BaseRelocatablePointer
     /// @param[in] other is the BaseRelocatablePointer
     RelocatablePointer(const BaseRelocatablePointer& other) noexcept;
 
-    /// @brief creates a RelocatablePointer pointing to rawPtr
-    /// @param[in] rawPtr is the pointee
+    /// @brief creates a RelocatablePointer pointing to the same pointee as rawPtr
+    /// @param[in] rawPtr the pointer whose pointee shall be the same for this
     RelocatablePointer(T* rawPtr) noexcept;
 
-    /// @brief assign this to point to the BaseRelocatablePointer other
-    /// @param[in] other is the pointee
+    /// @brief assign this to point to the same pointee as the BaseRelocatablePointer other
+    /// @param[in] other the pointer whose pointee shall be the same for this
     /// @return reference to self
     RelocatablePointer& operator=(const BaseRelocatablePointer& other) noexcept;