doxygen: score: adjust doc in protectedheap.h to doxygen guidelines

Update #3706.

cpukit/include/rtems/score/protectedheap.h

@@ -34,11 +34,16 @@ extern "C" {
  *
  * The @ref ScoreAllocatorMutex is used to protect the heap accesses.
  *
+ * @{
  */
-/**@{**/
 
 /**
- * @brief See _Heap_Initialize().
+ * @brief Initializes the protected heap.
+ *
+ * @param[out] heap The heap to initialize.
+ * @param area_begin The starting address of the heap area.
+ * @param area_size The size of the heap area.
+ * @param page_size The page size for the heap.
  */
 RTEMS_INLINE_ROUTINE uintptr_t _Protected_heap_Initialize(
   Heap_Control *heap,
@@ -51,9 +56,14 @@ RTEMS_INLINE_ROUTINE uintptr_t _Protected_heap_Initialize(
 }
 
 /**
- * @brief See _Heap_Extend().
+ * @brief Extends the protected heap.
  *
- * Returns @a true in case of success, and @a false otherwise.
+ * @param[in, out] heap The heap to extend.
+ * @param area_begin The starting addres of the area to extend @a heap with.
+ * @param area_size The size of the heap area.
+ *
+ * @retval true The operation succeeded.
+ * @retval false The operation failed.
  */
 bool _Protected_heap_Extend(
   Heap_Control *heap,
@@ -62,7 +72,23 @@ bool _Protected_heap_Extend(
 );
 
 /**
- * @brief See _Heap_Allocate_aligned_with_boundary().
+ * @brief Allocates an aligned memory area with boundary constraint for the protected heap.
+ *
+ * A size value of zero will return a unique address which may be freed with
+ * _Heap_Free().  This method first locks the allocator and after the allocation of the memory
+ * area, unlocks it again.
+ *
+ * @param[in, out] heap The heap to allocate a memory are from.
+ * @param size The size of the desired memory are in bytes.
+ * @param alignment The allocated memory area will begin at an address aligned by this value.
+ * @param boundary The allocated memory area will fulfill a boundary constraint,
+ *      if this value is not equal to zero.  The boundary value specifies
+ *      the set of addresses which are aligned by the boundary value.  The
+ *      interior of the allocated memory area will not contain an element of this
+ *      set.  The begin or end address of the area may be a member of the set.
+ *
+ * @retval pointer The starting address of the allocated memory area.
+ * @retval NULL No memory is available of the parameters are inconsistent.
  */
 void *_Protected_heap_Allocate_aligned_with_boundary(
   Heap_Control *heap,
@@ -72,7 +98,18 @@ void *_Protected_heap_Allocate_aligned_with_boundary(
 );
 
 /**
- * @brief See _Heap_Allocate_aligned_with_boundary() with boundary equals zero.
+ * @brief Allocates an aligned memory area.
+ *
+ * A size value of zero will return a unique address which may be freed with
+ * _Heap_Free().  This method first locks the allocator and after the allocation of the memory
+ * area, unlocks it again.
+ *
+ * @param[in, out] heap The heap to allocate a memory are from.
+ * @param size The size of the desired memory are in bytes.
+ * @param alignment The allocated memory area will begin at an address aligned by this value.
+ *
+ * @retval pointer The starting address of the allocated memory area.
+ * @retval NULL No memory is available of the parameters are inconsistent.
  */
 RTEMS_INLINE_ROUTINE void *_Protected_heap_Allocate_aligned(
   Heap_Control *heap,
@@ -85,8 +122,17 @@ RTEMS_INLINE_ROUTINE void *_Protected_heap_Allocate_aligned(
 }
 
 /**
- * @brief See _Heap_Allocate_aligned_with_boundary() with alignment and
- * boundary equals zero.
+ * @brief Allocates a memory area.
+ *
+ * A size value of zero will return a unique address which may be freed with
+ * _Heap_Free().  This method first locks the allocator and after the allocation of the memory
+ * area, unlocks it again.
+ *
+ * @param[in, out] heap The heap to allocate a memory are from.
+ * @param size The size of the desired memory are in bytes.
+ *
+ * @retval pointer The starting address of the allocated memory area.
+ * @retval NULL No memory is available of the parameters are inconsistent.
  */
 RTEMS_INLINE_ROUTINE void *_Protected_heap_Allocate(
   Heap_Control *heap,
@@ -97,7 +143,22 @@ RTEMS_INLINE_ROUTINE void *_Protected_heap_Allocate(
 }
 
 /**
- * @brief See _Heap_Size_of_alloc_area().
+ * @brief Returns the size of the allocatable memory area.
+ *
+ * The size value may be greater than the initially requested size in
+ * _Heap_Allocate_aligned_with_boundary().
+ *
+ * Inappropriate values for @a addr will not corrupt the heap, but may yield
+ * invalid size values.
+ *
+ * This method first locks the allocator and after the operation, unlocks it again.
+ *
+ * @param heap The heap to operate upon.
+ * @param addr The starting address of the allocatable memory area.
+ * @param[out] size Stores the size of the allocatable memory area after the method call.
+ *
+ * @retval true The operation was successful.
+ * @retval false The operation was not successful.
  */
 bool _Protected_heap_Get_block_size(
   Heap_Control *heap,
@@ -106,9 +167,27 @@ bool _Protected_heap_Get_block_size(
 );
 
 /**
- * @brief See _Heap_Resize_block().
+ * @brief Resizes the block of the allocated memory area.
  *
- * Returns @a true in case of success, and @a false otherwise.
+ * Inappropriate values for @a addr may corrupt the heap.
+ *
+ * This method first locks the allocator and after the resize, unlocks it again.
+ *
+ * @param[in, out] heap The heap to operate upon.
+ * @param addr The starting address of the allocated memory area to be resized.
+ * @param size The least possible size for the new memory area.  Resize may be
+ *      impossible and depends on the current heap usage.
+ * @param[out] old_size Stores the size available for allocation in the current
+ *      block before the resize after the method call.
+ * @param[out] new_size Stores the size available for allocation in the resized
+ *      block after the method call.  In the case of an unsuccessful resize,
+ *      zero is returned in this parameter
+ *
+ * @retval HEAP_RESIZE_SUCCESSFUL The resize was successful.
+ * @retval HEAP_RESIZE_UNSATISFIED The least possible size @a size was too big.
+ *      Resize not possible.
+ * @retval HEAP_RESIZE_FATAL_ERROR The block starting at @a addr is not part of
+ *      the heap.
  */
 bool _Protected_heap_Resize_block(
   Heap_Control *heap,
@@ -117,19 +196,43 @@ bool _Protected_heap_Resize_block(
 );
 
 /**
- * @brief See _Heap_Free().
+ * @brief Frees the allocated memory area.
  *
- * Returns @a true in case of success, and @a false otherwise.
+ * Inappropriate values for @a addr may corrupt the heap.  This method first locks
+ * the allocator and after the free operation, unlocks it again.
+ *
+ * @param[in, out] heap The heap of the allocated memory area.
+ * @param addr The starting address of the memory area to be freed.
+ *
+ * @retval true The allocated memory area was successfully freed.
+ * @retval false The method failed.
  */
 bool _Protected_heap_Free( Heap_Control *heap, void *addr );
 
 /**
- * @brief See _Heap_Walk().
+ * @brief Verifies the integrity of the heap.
+ *
+ * Walks the heap to verify its integrity.  This method first locks
+ * the allocator and after the operation, unlocks it again, if the thread dispatch is enabled.
+ *
+ * @param heap The heap whose integrity is to be verified.
+ * @param source If @a dump is @c true, this is used to mark the output lines.
+ * @param dump Indicates whether diagnostic messages will be printed to standard output.
+ *
+ * @retval true No errors occured, the heap´s integrity is not violated.
+ * @retval false The heap is corrupt.
  */
 bool _Protected_heap_Walk( Heap_Control *heap, int source, bool dump );
 
 /**
- * @brief See _Heap_Iterate().
+ * @brief Iterates over all blocks of the heap.
+ *
+ * This method first locks the allocator and after the operation, unlocks it again.
+ *
+ * @param[in, out] heap The heap to iterate over.
+ * @param visitor This will be called for each heap block with
+ *      the argument @a visitor_arg.
+ * @param[in, out] visitor_arg The argument for all calls of @a visitor.
  */
 void _Protected_heap_Iterate(
   Heap_Control *heap,
@@ -138,9 +241,12 @@ void _Protected_heap_Iterate(
 );
 
 /**
- * @brief See _Heap_Get_information().
+ * @brief Returns information about used and free blocks for the heap.
  *
- * Returns @a true in case of success, and @a false otherwise.
+ * This method first locks the allocator and after the operation, unlocks it again.
+ *
+ * @param heap The heap to get the information from.
+ * @param[out] info Stores the information of the @a heap after the method call.
  */
 bool _Protected_heap_Get_information(
   Heap_Control *heap,
@@ -148,9 +254,13 @@ bool _Protected_heap_Get_information(
 );
 
 /**
- * @brief See _Heap_Get_free_information().
+ * @brief Returns information about free blocks for the heap.
  *
- * Returns @a true in case of success, and @a false otherwise.
+ * This method first locks the allocator and after the operation, unlocks it again.
+ *
+ * @param heap The heap to get the information from.
+ * @param[out] info Stores the information about free blocks of @a heap after the
+ *      method call.
  */
 bool _Protected_heap_Get_free_information(
   Heap_Control *heap,
@@ -158,7 +268,13 @@ bool _Protected_heap_Get_free_information(
 );
 
 /**
- * @brief See _Heap_Get_size().
+ * @brief Returns the size of the allocatable area in bytes.
+ *
+ * This value is an integral multiple of the page size.
+ *
+ * @param heap The heap to get the allocatable area from.
+ *
+ * @return The size of the allocatable area in @a heap in bytes.
  */
 uintptr_t _Protected_heap_Get_size( Heap_Control *heap );