doxygen: Rework some Doxygen comments

They are intended as examples in the RTEMS Software Engineering manual.

Update #3704.

2 files changed, 9 insertions, 12 deletions

diff --git a/cpukit/include/rtems/score/rbtree.h b/cpukit/include/rtems/score/rbtree.h
index 51f9125dda..c01a893b6e 100644
--- a/cpukit/include/rtems/score/rbtree.h
+++ b/cpukit/include/rtems/score/rbtree.h
@@ -106,8 +106,8 @@ RTEMS_INLINE_ROUTINE bool _RBTree_Is_node_off_tree(
 /**
  * @brief Rebalances the red-black tree after insertion of the node.
  *
- * @param[in] the_rbtree The red-black tree control.
- * @param[in] the_node The most recently inserted node.
+ * @param[in, out] the_rbtree The red-black tree control.
+ * @param[in, out] the_node The most recently inserted node.
  */
 void _RBTree_Insert_color(
   RBTree_Control *the_rbtree,
diff --git a/cpukit/include/rtems/score/wkspace.h b/cpukit/include/rtems/score/wkspace.h
index cbb4011824..551a10d50d 100644
--- a/cpukit/include/rtems/score/wkspace.h
+++ b/cpukit/include/rtems/score/wkspace.h
@@ -57,19 +57,16 @@ void _Workspace_Handler_initialization(
 );
 
 /**
- * @brief Allocate memory from workspace.
+ * @brief Allocates a memory block of the specified size from the workspace.
  *
- *  This routine returns the address of a block of memory of size
- *  bytes.  If a block of the appropriate size cannot be allocated
- *  from the workspace, then NULL is returned.
- *
- *  @param size is the requested size
+ * @param size The size of the memory block.
  *
- *  @retval a pointer to the requested memory or NULL.
+ * @retval pointer The pointer to the memory block.  The pointer is at least
+ *   aligned by CPU_HEAP_ALIGNMENT.
+ * @retval NULL No memory block with the requested size is available in the
+ *   workspace.
  */
-void *_Workspace_Allocate(
-  size_t   size
-);
+void *_Workspace_Allocate( size_t size );
 
 /**
  * @brief Allocate aligned memory from workspace.