docs: add FreeRTOS API docs

- Use `code` tags instead of a mix of `<pre></pre>` and
  `@verbatim .. @endverbatim`
- Remove manually added function prototypes from comment blocks
- Remove of grouping (`\defgroup`) — some extra work is needed
  to make groups compatible with the way we auto-generate API
  reference from Doxygen XML files. It's pretty easy to add the
  grouping directives back if/when we implement support for
  Doxygen groups in the later stages of documentation build
  process.
- Hide private APIs under `@cond .. @endcond`
- Convert some comments into Doxygen-compatible ones
- Fix various documentation issues: missing documentation for
  some parameters, mismatch between parameter names in comment
  block and in function prototype.
- Add doxygen comments for functions which didn't have them
  (thread local storage).
- Add [out] param tags where necessary
- Redefine `xTaskCreate` and `xTaskCreateStatic` as inline
  functions instead of macros.

components/freertos/include/freertos/event_groups.h

@@ -104,7 +104,6 @@ extern "C" {
  * used to create a synchronisation point between multiple tasks (a
  * 'rendezvous').
  *
- * \defgroup EventGroup
  */
 
 
@@ -116,7 +115,6 @@ extern "C" {
  * xEventGroupCreate() returns an EventGroupHandle_t variable that can then
  * be used as a parameter to other event group functions.
  *
- * \defgroup EventGroupHandle_t EventGroupHandle_t
  * \ingroup EventGroup
  */
 typedef void * EventGroupHandle_t;
@@ -126,17 +124,11 @@ typedef void * EventGroupHandle_t;
  * number of bits it holds is set by configUSE_16_BIT_TICKS (16 bits if set to 1,
  * 32 bits if set to 0. 
  *
- * \defgroup EventBits_t EventBits_t
  * \ingroup EventGroup
  */
 typedef TickType_t EventBits_t;
 
 /**
- * event_groups.h
- *<pre>
- EventGroupHandle_t xEventGroupCreate( void );
- </pre>
- *
  * Create a new event group.
  *
  * Internally, within the FreeRTOS implementation, event groups use a [small]
@@ -162,25 +154,24 @@ typedef TickType_t EventBits_t;
  * event group then NULL is returned.  See http://www.freertos.org/a00111.html
  *
  * Example usage:
-   <pre>
-	// Declare a variable to hold the created event group.
-	EventGroupHandle_t xCreatedEventGroup;
-
-	// Attempt to create the event group.
-	xCreatedEventGroup = xEventGroupCreate();
-
-	// Was the event group created successfully?
-	if( xCreatedEventGroup == NULL )
-	{
-		// The event group was not created because there was insufficient
-		// FreeRTOS heap available.
-	}
-	else
-	{
-		// The event group was created.
-	}
-   </pre>
- * \defgroup xEventGroupCreate xEventGroupCreate
+ * @code{c}
+ * 	// Declare a variable to hold the created event group.
+ * 	EventGroupHandle_t xCreatedEventGroup;
+ *
+ * 	// Attempt to create the event group.
+ * 	xCreatedEventGroup = xEventGroupCreate();
+ *
+ * 	// Was the event group created successfully?
+ * 	if( xCreatedEventGroup == NULL )
+ * 	{
+ * 		// The event group was not created because there was insufficient
+ * 		// FreeRTOS heap available.
+ * 	}
+ * 	else
+ * 	{
+ * 		// The event group was created.
+ * 	}
+ * @endcode
  * \ingroup EventGroup
  */
 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
@@ -188,11 +179,6 @@ typedef TickType_t EventBits_t;
 #endif
 
 /**
- * event_groups.h
- *<pre>
- EventGroupHandle_t xEventGroupCreateStatic( EventGroupHandle_t * pxEventGroupBuffer );
- </pre>
- *
  * Create a new event group.
  *
  * Internally, within the FreeRTOS implementation, event groups use a [small]
@@ -221,35 +207,26 @@ typedef TickType_t EventBits_t;
  * returned.  If pxEventGroupBuffer was NULL then NULL is returned.
  *
  * Example usage:
-   <pre>
-	// StaticEventGroup_t is a publicly accessible structure that has the same
-	// size and alignment requirements as the real event group structure.  It is
-	// provided as a mechanism for applications to know the size of the event
-	// group (which is dependent on the architecture and configuration file
-	// settings) without breaking the strict data hiding policy by exposing the
-	// real event group internals.  This StaticEventGroup_t variable is passed
-	// into the xSemaphoreCreateEventGroupStatic() function and is used to store
-	// the event group's data structures
-	StaticEventGroup_t xEventGroupBuffer;
-
-	// Create the event group without dynamically allocating any memory.
-	xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
-   </pre>
+ * @code{c}
+ * 	// StaticEventGroup_t is a publicly accessible structure that has the same
+ * 	// size and alignment requirements as the real event group structure.  It is
+ * 	// provided as a mechanism for applications to know the size of the event
+ * 	// group (which is dependent on the architecture and configuration file
+ * 	// settings) without breaking the strict data hiding policy by exposing the
+ * 	// real event group internals.  This StaticEventGroup_t variable is passed
+ * 	// into the xSemaphoreCreateEventGroupStatic() function and is used to store
+ * 	// the event group's data structures
+ * 	StaticEventGroup_t xEventGroupBuffer;
+ *
+ * 	// Create the event group without dynamically allocating any memory.
+ * 	xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
+ * @endcode
  */
 #if( configSUPPORT_STATIC_ALLOCATION == 1 )
 	EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer ) PRIVILEGED_FUNCTION;
 #endif
 
 /**
- * event_groups.h
- *<pre>
-	EventBits_t xEventGroupWaitBits( 	EventGroupHandle_t xEventGroup,
-										const EventBits_t uxBitsToWaitFor,
-										const BaseType_t xClearOnExit,
-										const BaseType_t xWaitForAllBits,
-										const TickType_t xTicksToWait );
- </pre>
- *
  * [Potentially] block to wait for one or more bits to be set within a
  * previously created event group.
  *
@@ -292,54 +269,48 @@ typedef TickType_t EventBits_t;
  * pdTRUE.
  *
  * Example usage:
-   <pre>
-   #define BIT_0	( 1 << 0 )
-   #define BIT_4	( 1 << 4 )
-
-   void aFunction( EventGroupHandle_t xEventGroup )
-   {
-   EventBits_t uxBits;
-   const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
-
-		// Wait a maximum of 100ms for either bit 0 or bit 4 to be set within
-		// the event group.  Clear the bits before exiting.
-		uxBits = xEventGroupWaitBits(
-					xEventGroup,	// The event group being tested.
-					BIT_0 | BIT_4,	// The bits within the event group to wait for.
-					pdTRUE,			// BIT_0 and BIT_4 should be cleared before returning.
-					pdFALSE,		// Don't wait for both bits, either bit will do.
-					xTicksToWait );	// Wait a maximum of 100ms for either bit to be set.
-
-		if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
-		{
-			// xEventGroupWaitBits() returned because both bits were set.
-		}
-		else if( ( uxBits & BIT_0 ) != 0 )
-		{
-			// xEventGroupWaitBits() returned because just BIT_0 was set.
-		}
-		else if( ( uxBits & BIT_4 ) != 0 )
-		{
-			// xEventGroupWaitBits() returned because just BIT_4 was set.
-		}
-		else
-		{
-			// xEventGroupWaitBits() returned because xTicksToWait ticks passed
-			// without either BIT_0 or BIT_4 becoming set.
-		}
-   }
-   </pre>
- * \defgroup xEventGroupWaitBits xEventGroupWaitBits
+ * @code{c}
+ *    #define BIT_0	( 1 << 0 )
+ *    #define BIT_4	( 1 << 4 )
+ *
+ *    void aFunction( EventGroupHandle_t xEventGroup )
+ *    {
+ *    EventBits_t uxBits;
+ *    const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
+ *
+ * 		// Wait a maximum of 100ms for either bit 0 or bit 4 to be set within
+ * 		// the event group.  Clear the bits before exiting.
+ * 		uxBits = xEventGroupWaitBits(
+ * 					xEventGroup,	// The event group being tested.
+ * 					BIT_0 | BIT_4,	// The bits within the event group to wait for.
+ * 					pdTRUE,			// BIT_0 and BIT_4 should be cleared before returning.
+ * 					pdFALSE,		// Don't wait for both bits, either bit will do.
+ * 					xTicksToWait );	// Wait a maximum of 100ms for either bit to be set.
+ *
+ * 		if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
+ * 		{
+ * 			// xEventGroupWaitBits() returned because both bits were set.
+ * 		}
+ * 		else if( ( uxBits & BIT_0 ) != 0 )
+ * 		{
+ * 			// xEventGroupWaitBits() returned because just BIT_0 was set.
+ * 		}
+ * 		else if( ( uxBits & BIT_4 ) != 0 )
+ * 		{
+ * 			// xEventGroupWaitBits() returned because just BIT_4 was set.
+ * 		}
+ * 		else
+ * 		{
+ * 			// xEventGroupWaitBits() returned because xTicksToWait ticks passed
+ * 			// without either BIT_0 or BIT_4 becoming set.
+ * 		}
+ *    }
+ * @endcode{c}
  * \ingroup EventGroup
  */
 EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
 
 /**
- * event_groups.h
- *<pre>
-	EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );
- </pre>
- *
  * Clear bits within an event group.  This function cannot be called from an
  * interrupt.
  *
@@ -352,51 +323,45 @@ EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, const EventBits
  * @return The value of the event group before the specified bits were cleared.
  *
  * Example usage:
-   <pre>
-   #define BIT_0	( 1 << 0 )
-   #define BIT_4	( 1 << 4 )
-
-   void aFunction( EventGroupHandle_t xEventGroup )
-   {
-   EventBits_t uxBits;
-
-		// Clear bit 0 and bit 4 in xEventGroup.
-		uxBits = xEventGroupClearBits(
-								xEventGroup,	// The event group being updated.
-								BIT_0 | BIT_4 );// The bits being cleared.
-
-		if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
-		{
-			// Both bit 0 and bit 4 were set before xEventGroupClearBits() was
-			// called.  Both will now be clear (not set).
-		}
-		else if( ( uxBits & BIT_0 ) != 0 )
-		{
-			// Bit 0 was set before xEventGroupClearBits() was called.  It will
-			// now be clear.
-		}
-		else if( ( uxBits & BIT_4 ) != 0 )
-		{
-			// Bit 4 was set before xEventGroupClearBits() was called.  It will
-			// now be clear.
-		}
-		else
-		{
-			// Neither bit 0 nor bit 4 were set in the first place.
-		}
-   }
-   </pre>
- * \defgroup xEventGroupClearBits xEventGroupClearBits
+ * @code{c}
+ *    #define BIT_0	( 1 << 0 )
+ *    #define BIT_4	( 1 << 4 )
+ *
+ *    void aFunction( EventGroupHandle_t xEventGroup )
+ *    {
+ *    EventBits_t uxBits;
+ *
+ * 		// Clear bit 0 and bit 4 in xEventGroup.
+ * 		uxBits = xEventGroupClearBits(
+ * 								xEventGroup,	// The event group being updated.
+ * 								BIT_0 | BIT_4 );// The bits being cleared.
+ *
+ * 		if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
+ * 		{
+ * 			// Both bit 0 and bit 4 were set before xEventGroupClearBits() was
+ * 			// called.  Both will now be clear (not set).
+ * 		}
+ * 		else if( ( uxBits & BIT_0 ) != 0 )
+ * 		{
+ * 			// Bit 0 was set before xEventGroupClearBits() was called.  It will
+ * 			// now be clear.
+ * 		}
+ * 		else if( ( uxBits & BIT_4 ) != 0 )
+ * 		{
+ * 			// Bit 4 was set before xEventGroupClearBits() was called.  It will
+ * 			// now be clear.
+ * 		}
+ * 		else
+ * 		{
+ * 			// Neither bit 0 nor bit 4 were set in the first place.
+ * 		}
+ *    }
+ * @endcode
  * \ingroup EventGroup
  */
 EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION;
 
 /**
- * event_groups.h
- *<pre>
-	BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
- </pre>
- *
  * A version of xEventGroupClearBits() that can be called from an interrupt.
  *
  * Setting bits in an event group is not a deterministic operation because there
@@ -420,28 +385,27 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBit
  * if the timer service queue was full.
  *
  * Example usage:
-   <pre>
-   #define BIT_0	( 1 << 0 )
-   #define BIT_4	( 1 << 4 )
-
-   // An event group which it is assumed has already been created by a call to
-   // xEventGroupCreate().
-   EventGroupHandle_t xEventGroup;
-
-   void anInterruptHandler( void )
-   {
-		// Clear bit 0 and bit 4 in xEventGroup.
-		xResult = xEventGroupClearBitsFromISR(
-							xEventGroup,	 // The event group being updated.
-							BIT_0 | BIT_4 ); // The bits being set.
-
-		if( xResult == pdPASS )
-		{
-			// The message was posted successfully.
-		}
-  }
-   </pre>
- * \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR
+ * @code{c}
+ *    #define BIT_0	( 1 << 0 )
+ *    #define BIT_4	( 1 << 4 )
+ *
+ *    // An event group which it is assumed has already been created by a call to
+ *    // xEventGroupCreate().
+ *    EventGroupHandle_t xEventGroup;
+ *
+ *    void anInterruptHandler( void )
+ *    {
+ * 		// Clear bit 0 and bit 4 in xEventGroup.
+ * 		xResult = xEventGroupClearBitsFromISR(
+ * 							xEventGroup,	 // The event group being updated.
+ * 							BIT_0 | BIT_4 ); // The bits being set.
+ *
+ * 		if( xResult == pdPASS )
+ * 		{
+ * 			// The message was posted successfully.
+ * 		}
+ *   }
+ * @endcode
  * \ingroup EventGroup
  */
 #if( configUSE_TRACE_FACILITY == 1 )
@@ -451,11 +415,6 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBit
 #endif
 
 /**
- * event_groups.h
- *<pre>
-	EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
- </pre>
- *
  * Set bits within an event group.
  * This function cannot be called from an interrupt.  xEventGroupSetBitsFromISR()
  * is a version that can be called from an interrupt.
@@ -480,56 +439,50 @@ EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBit
  * event group value before the call to xEventGroupSetBits() returns.
  *
  * Example usage:
-   <pre>
-   #define BIT_0	( 1 << 0 )
-   #define BIT_4	( 1 << 4 )
-
-   void aFunction( EventGroupHandle_t xEventGroup )
-   {
-   EventBits_t uxBits;
-
-		// Set bit 0 and bit 4 in xEventGroup.
-		uxBits = xEventGroupSetBits(
-							xEventGroup,	// The event group being updated.
-							BIT_0 | BIT_4 );// The bits being set.
-
-		if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
-		{
-			// Both bit 0 and bit 4 remained set when the function returned.
-		}
-		else if( ( uxBits & BIT_0 ) != 0 )
-		{
-			// Bit 0 remained set when the function returned, but bit 4 was
-			// cleared.  It might be that bit 4 was cleared automatically as a
-			// task that was waiting for bit 4 was removed from the Blocked
-			// state.
-		}
-		else if( ( uxBits & BIT_4 ) != 0 )
-		{
-			// Bit 4 remained set when the function returned, but bit 0 was
-			// cleared.  It might be that bit 0 was cleared automatically as a
-			// task that was waiting for bit 0 was removed from the Blocked
-			// state.
-		}
-		else
-		{
-			// Neither bit 0 nor bit 4 remained set.  It might be that a task
-			// was waiting for both of the bits to be set, and the bits were
-			// cleared as the task left the Blocked state.
-		}
-   }
-   </pre>
- * \defgroup xEventGroupSetBits xEventGroupSetBits
+ * @code{c}
+ *    #define BIT_0	( 1 << 0 )
+ *    #define BIT_4	( 1 << 4 )
+ *
+ *    void aFunction( EventGroupHandle_t xEventGroup )
+ *    {
+ *    EventBits_t uxBits;
+ *
+ * 		// Set bit 0 and bit 4 in xEventGroup.
+ * 		uxBits = xEventGroupSetBits(
+ * 							xEventGroup,	// The event group being updated.
+ * 							BIT_0 | BIT_4 );// The bits being set.
+ *
+ * 		if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
+ * 		{
+ * 			// Both bit 0 and bit 4 remained set when the function returned.
+ * 		}
+ * 		else if( ( uxBits & BIT_0 ) != 0 )
+ * 		{
+ * 			// Bit 0 remained set when the function returned, but bit 4 was
+ * 			// cleared.  It might be that bit 4 was cleared automatically as a
+ * 			// task that was waiting for bit 4 was removed from the Blocked
+ * 			// state.
+ * 		}
+ * 		else if( ( uxBits & BIT_4 ) != 0 )
+ * 		{
+ * 			// Bit 4 remained set when the function returned, but bit 0 was
+ * 			// cleared.  It might be that bit 0 was cleared automatically as a
+ * 			// task that was waiting for bit 0 was removed from the Blocked
+ * 			// state.
+ * 		}
+ * 		else
+ * 		{
+ * 			// Neither bit 0 nor bit 4 remained set.  It might be that a task
+ * 			// was waiting for both of the bits to be set, and the bits were
+ * 			// cleared as the task left the Blocked state.
+ * 		}
+ *    }
+ * @endcode{c}
  * \ingroup EventGroup
  */
 EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet ) PRIVILEGED_FUNCTION;
 
 /**
- * event_groups.h
- *<pre>
-	BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken );
- </pre>
- *
  * A version of xEventGroupSetBits() that can be called from an interrupt.
  *
  * Setting bits in an event group is not a deterministic operation because there
@@ -561,39 +514,38 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_
  * if the timer service queue was full.
  *
  * Example usage:
-   <pre>
-   #define BIT_0	( 1 << 0 )
-   #define BIT_4	( 1 << 4 )
-
-   // An event group which it is assumed has already been created by a call to
-   // xEventGroupCreate().
-   EventGroupHandle_t xEventGroup;
-
-   void anInterruptHandler( void )
-   {
-   BaseType_t xHigherPriorityTaskWoken, xResult;
-
-		// xHigherPriorityTaskWoken must be initialised to pdFALSE.
-		xHigherPriorityTaskWoken = pdFALSE;
-
-		// Set bit 0 and bit 4 in xEventGroup.
-		xResult = xEventGroupSetBitsFromISR(
-							xEventGroup,	// The event group being updated.
-							BIT_0 | BIT_4   // The bits being set.
-							&xHigherPriorityTaskWoken );
-
-		// Was the message posted successfully?
-		if( xResult == pdPASS )
-		{
-			// If xHigherPriorityTaskWoken is now set to pdTRUE then a context
-			// switch should be requested.  The macro used is port specific and 
-			// will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - 
-			// refer to the documentation page for the port being used.
-			portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
-		}
-  }
-   </pre>
- * \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR
+ * @code{c}
+ *    #define BIT_0	( 1 << 0 )
+ *    #define BIT_4	( 1 << 4 )
+ *
+ *    // An event group which it is assumed has already been created by a call to
+ *    // xEventGroupCreate().
+ *    EventGroupHandle_t xEventGroup;
+ *
+ *    void anInterruptHandler( void )
+ *    {
+ *    BaseType_t xHigherPriorityTaskWoken, xResult;
+ *
+ * 		// xHigherPriorityTaskWoken must be initialised to pdFALSE.
+ * 		xHigherPriorityTaskWoken = pdFALSE;
+ *
+ * 		// Set bit 0 and bit 4 in xEventGroup.
+ * 		xResult = xEventGroupSetBitsFromISR(
+ * 							xEventGroup,	// The event group being updated.
+ * 							BIT_0 | BIT_4   // The bits being set.
+ * 							&xHigherPriorityTaskWoken );
+ *
+ * 		// Was the message posted successfully?
+ * 		if( xResult == pdPASS )
+ * 		{
+ * 			// If xHigherPriorityTaskWoken is now set to pdTRUE then a context
+ * 			// switch should be requested.  The macro used is port specific and
+ * 			// will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
+ * 			// refer to the documentation page for the port being used.
+ * 			portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
+ * 		}
+ *   }
+ * @endcode
  * \ingroup EventGroup
  */
 #if( configUSE_TRACE_FACILITY == 1 )
@@ -603,14 +555,6 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_
 #endif
 
 /**
- * event_groups.h
- *<pre>
-	EventBits_t xEventGroupSync(	EventGroupHandle_t xEventGroup,
-									const EventBits_t uxBitsToSet,
-									const EventBits_t uxBitsToWaitFor,
-									TickType_t xTicksToWait );
- </pre>
- *
  * Atomically set bits within an event group, then wait for a combination of
  * bits to be set within the same event group.  This functionality is typically
  * used to synchronise multiple tasks, where each task has to wait for the other
@@ -648,93 +592,87 @@ EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_
  * automatically cleared.
  *
  * Example usage:
- <pre>
- // Bits used by the three tasks.
- #define TASK_0_BIT		( 1 << 0 )
- #define TASK_1_BIT		( 1 << 1 )
- #define TASK_2_BIT		( 1 << 2 )
-
- #define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT )
-
- // Use an event group to synchronise three tasks.  It is assumed this event
- // group has already been created elsewhere.
- EventGroupHandle_t xEventBits;
-
- void vTask0( void *pvParameters )
- {
- EventBits_t uxReturn;
- TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
-
-	 for( ;; )
-	 {
-		// Perform task functionality here.
-
-		// Set bit 0 in the event flag to note this task has reached the
-		// sync point.  The other two tasks will set the other two bits defined
-		// by ALL_SYNC_BITS.  All three tasks have reached the synchronisation
-		// point when all the ALL_SYNC_BITS are set.  Wait a maximum of 100ms
-		// for this to happen.
-		uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS, xTicksToWait );
-
-		if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS )
-		{
-			// All three tasks reached the synchronisation point before the call
-			// to xEventGroupSync() timed out.
-		}
-	}
- }
-
- void vTask1( void *pvParameters )
- {
-	 for( ;; )
-	 {
-		// Perform task functionality here.
-
-		// Set bit 1 in the event flag to note this task has reached the
-		// synchronisation point.  The other two tasks will set the other two
-		// bits defined by ALL_SYNC_BITS.  All three tasks have reached the
-		// synchronisation point when all the ALL_SYNC_BITS are set.  Wait
-		// indefinitely for this to happen.
-		xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY );
-
-		// xEventGroupSync() was called with an indefinite block time, so
-		// this task will only reach here if the syncrhonisation was made by all
-		// three tasks, so there is no need to test the return value.
-	 }
- }
-
- void vTask2( void *pvParameters )
- {
-	 for( ;; )
-	 {
-		// Perform task functionality here.
-
-		// Set bit 2 in the event flag to note this task has reached the
-		// synchronisation point.  The other two tasks will set the other two
-		// bits defined by ALL_SYNC_BITS.  All three tasks have reached the
-		// synchronisation point when all the ALL_SYNC_BITS are set.  Wait
-		// indefinitely for this to happen.
-		xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY );
-
-		// xEventGroupSync() was called with an indefinite block time, so
-		// this task will only reach here if the syncrhonisation was made by all
-		// three tasks, so there is no need to test the return value.
-	}
- }
-
- </pre>
- * \defgroup xEventGroupSync xEventGroupSync
+ * @code{c}
+ *  // Bits used by the three tasks.
+ *  #define TASK_0_BIT		( 1 << 0 )
+ *  #define TASK_1_BIT		( 1 << 1 )
+ *  #define TASK_2_BIT		( 1 << 2 )
+ *
+ *  #define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT )
+ *
+ *  // Use an event group to synchronise three tasks.  It is assumed this event
+ *  // group has already been created elsewhere.
+ *  EventGroupHandle_t xEventBits;
+ *
+ *  void vTask0( void *pvParameters )
+ *  {
+ *  EventBits_t uxReturn;
+ *  TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
+ *
+ * 	 for( ;; )
+ * 	 {
+ * 		// Perform task functionality here.
+ *
+ * 		// Set bit 0 in the event flag to note this task has reached the
+ * 		// sync point.  The other two tasks will set the other two bits defined
+ * 		// by ALL_SYNC_BITS.  All three tasks have reached the synchronisation
+ * 		// point when all the ALL_SYNC_BITS are set.  Wait a maximum of 100ms
+ * 		// for this to happen.
+ * 		uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS, xTicksToWait );
+ *
+ * 		if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS )
+ * 		{
+ * 			// All three tasks reached the synchronisation point before the call
+ * 			// to xEventGroupSync() timed out.
+ * 		}
+ * 	}
+ *  }
+ *
+ *  void vTask1( void *pvParameters )
+ *  {
+ * 	 for( ;; )
+ * 	 {
+ * 		// Perform task functionality here.
+ *
+ * 		// Set bit 1 in the event flag to note this task has reached the
+ * 		// synchronisation point.  The other two tasks will set the other two
+ * 		// bits defined by ALL_SYNC_BITS.  All three tasks have reached the
+ * 		// synchronisation point when all the ALL_SYNC_BITS are set.  Wait
+ * 		// indefinitely for this to happen.
+ * 		xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY );
+ *
+ * 		// xEventGroupSync() was called with an indefinite block time, so
+ * 		// this task will only reach here if the syncrhonisation was made by all
+ * 		// three tasks, so there is no need to test the return value.
+ * 	 }
+ *  }
+ *
+ *  void vTask2( void *pvParameters )
+ *  {
+ * 	 for( ;; )
+ * 	 {
+ * 		// Perform task functionality here.
+ *
+ * 		// Set bit 2 in the event flag to note this task has reached the
+ * 		// synchronisation point.  The other two tasks will set the other two
+ * 		// bits defined by ALL_SYNC_BITS.  All three tasks have reached the
+ * 		// synchronisation point when all the ALL_SYNC_BITS are set.  Wait
+ * 		// indefinitely for this to happen.
+ * 		xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY );
+ *
+ * 		// xEventGroupSync() was called with an indefinite block time, so
+ * 		// this task will only reach here if the syncrhonisation was made by all
+ * 		// three tasks, so there is no need to test the return value.
+ * 	}
+ *  }
+ *
+ * @endcode
  * \ingroup EventGroup
  */
 EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
 
 
 /**
- * event_groups.h
- *<pre>
-	EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup );
- </pre>
- *
  * Returns the current value of the bits in an event group.  This function
  * cannot be used from an interrupt.
  *
@@ -742,33 +680,22 @@ EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t u
  *
  * @return The event group bits at the time xEventGroupGetBits() was called.
  *
- * \defgroup xEventGroupGetBits xEventGroupGetBits
  * \ingroup EventGroup
  */
 #define xEventGroupGetBits( xEventGroup ) xEventGroupClearBits( xEventGroup, 0 )
 
 /**
- * event_groups.h
- *<pre>
-	EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
- </pre>
- *
  * A version of xEventGroupGetBits() that can be called from an ISR.
  *
  * @param xEventGroup The event group being queried.
  *
  * @return The event group bits at the time xEventGroupGetBitsFromISR() was called.
  *
- * \defgroup xEventGroupGetBitsFromISR xEventGroupGetBitsFromISR
  * \ingroup EventGroup
  */
 EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
 
 /**
- * event_groups.h
- *<pre>
-	void xEventGroupDelete( EventGroupHandle_t xEventGroup );
- </pre>
  *
  * Delete an event group that was previously created by a call to
  * xEventGroupCreate().  Tasks that are blocked on the event group will be
@@ -778,6 +705,8 @@ EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
  */
 void vEventGroupDelete( EventGroupHandle_t xEventGroup );
 
+/** @cond */
+
 /* For internal use only. */
 void vEventGroupSetBitsCallback( void *pvEventGroup, const uint32_t ulBitsToSet );
 void vEventGroupClearBitsCallback( void *pvEventGroup, const uint32_t ulBitsToClear );
@@ -786,6 +715,8 @@ void vEventGroupClearBitsCallback( void *pvEventGroup, const uint32_t ulBitsToCl
 	UBaseType_t uxEventGroupGetNumber( void* xEventGroup );
 #endif
 
+/** @endcond */
+
 #ifdef __cplusplus
 }
 #endif

components/freertos/include/freertos/ringbuf.h

@@ -9,50 +9,58 @@
 extern "C" {
 #endif
 
-/*
-Header definitions for a FreeRTOS ringbuffer object
-
-A ringbuffer instantiated by these functions essentially acts like a FreeRTOS queue, with the
-difference that it's strictly FIFO and with the main advantage that you can put in randomly-sized
-items. The capacity, accordingly, isn't measured in the amount of items, but the amount of memory
-that is used for storing the items. Dependent on the size of the items, more or less of them will 
-fit in the ring buffer.
-
-This ringbuffer tries to be efficient with memory: when inserting an item, the item data will
-be copied to the ringbuffer memory. When retrieving an item, however, a reference to ringbuffer
-memory will be returned. The returned memory is guaranteed to be 32-bit aligned and contiguous.
-The application can use this memory, but as long as it does, ringbuffer writes that would write
-to this bit of memory will block.
-
-The requirement for items to be contiguous is slightly problematic when the only way to place
-the next item would involve a wraparound from the end to the beginning of the ringbuffer. This can
-be solved (or not) in a few ways:
-- type = RINGBUF_TYPE_ALLOWSPLIT: The insertion code will split the item in two items; one which fits
-in the space left at the end of the ringbuffer, one that contains the remaining data which is placed
-in the beginning. Two xRingbufferReceive calls will be needed to retrieve the data.
-- type = RINGBUF_TYPE_NOSPLIT: The insertion code will leave the room at the end of the ringbuffer
-unused and instead will put the entire item at the start of the ringbuffer, as soon as there is 
-enough free space.
-- type = RINGBUF_TYPE_BYTEBUF: This is your conventional byte-based ringbuffer. It does have no
-overhead, but it has no item contiguousness either: a read will just give you the entire written
-buffer space, or the space up to the end of the buffer, and writes can be broken up in any way 
-possible. Note that this type cannot do a 2nd read before returning the memory of the 1st.
-
-The maximum size of an item will be affected by this decision. When split items are allowed, it's
-acceptable to push items of (buffer_size)-16 bytes into the buffer. When it's not allowed, the
-maximum size is (buffer_size/2)-8 bytes. The bytebuf can fill the entire buffer with data, it has
-no overhead.
-*/
-
 #include <freertos/queue.h>
 
 //An opaque handle for a ringbuff object.
 typedef void * RingbufHandle_t;
 
-//The various types of buffer
+/**
+ * @brief The various types of buffer
+ *
+ * A ringbuffer instantiated by these functions essentially acts like a
+ * FreeRTOS queue, with the difference that it's strictly FIFO and with
+ * the main advantage that you can put in randomly-sized items. The capacity,
+ * accordingly, isn't measured in the amount of items, but the amount of
+ * memory that is used for storing the items. Dependent on the size of
+ * the items, more or less of them will fit in the ring buffer.
+ *
+ * This ringbuffer tries to be efficient with memory: when inserting an item,
+ * the item data will be copied to the ringbuffer memory. When retrieving
+ * an item, however, a reference to ringbuffer memory will be returned.
+ * The returned memory is guaranteed to be 32-bit aligned and contiguous.
+ * The application can use this memory, but as long as it does, ringbuffer
+ * writes that would write to this bit of memory will block.
+ *
+ * The requirement for items to be contiguous is slightly problematic when
+ * the only way to place the next item would involve a wraparound from the end
+ * to the beginning of the ringbuffer. This can be solved (or not) in a few ways,
+ * see descriptions of possible ringbuf_type_t types below.
+ *
+ * The maximum size of an item will be affected by ringbuffer type.
+ * When split items are allowed, it is acceptable to push items of
+ * (buffer_size)-16 bytes into the buffer.
+ * When it's not allowed, the maximum size is (buffer_size/2)-8 bytes.
+ * The bytebuf can fill the entire buffer with data, it has no overhead.
+ */
 typedef enum {
+	/** The insertion code will leave the room at the end of the ringbuffer
+	 * unused and instead will put the entire item at the start of the ringbuffer,
+	 * as soon as there is enough free space.
+	 */
 	RINGBUF_TYPE_NOSPLIT = 0,
+	/** The insertion code will split the item in two items; one which fits
+	 * in the space left at the end of the ringbuffer, one that contains
+	 * the remaining data which is placed in the beginning.
+	 * Two xRingbufferReceive calls will be needed to retrieve the data.
+	 */
 	RINGBUF_TYPE_ALLOWSPLIT,
+	/** This is your conventional byte-based ringbuffer. It does have no
+	 * overhead, but it has no item contiguousness either: a read will just
+	 * give you the entire written buffer space, or the space up to the end
+	 * of the buffer, and writes can be broken up in any way possible.
+	 * Note that this type cannot do a 2nd read before returning the memory
+	 * of the 1st.
+	 */
 	RINGBUF_TYPE_BYTEBUF
 } ringbuf_type_t;
 
@@ -60,22 +68,19 @@ typedef enum {
 /**
  * @brief  Create a ring buffer
  *
- * @param  buf_length : Length of circular buffer, in bytes. Each entry will take up its own length, plus a header
- *                      that at the moment is equal to sizeof(size_t).
- * @param allow_split_items : pdTRUE if it is acceptable that item data is inserted as two
- *                            items instead of one.
+ * @param  buf_length  Length of circular buffer, in bytes. Each entry will
+ *                     take up its own length, plus a header that at the moment
+ *                     is equal to sizeof(size_t).
+ * @param  type  Type of ring buffer, see ringbuf_type_t.
  *
  * @return A RingbufHandle_t handle to the created ringbuffer, or NULL in case of error.
  */
 RingbufHandle_t xRingbufferCreate(size_t buf_length, ringbuf_type_t type);
 
-
 /**
  * @brief  Delete a ring buffer
  *
- * @param  ringbuf - Ring buffer to delete
- *
- * @return void
+ * @param  ringbuf  Ring buffer to delete
  */
 void vRingbufferDelete(RingbufHandle_t ringbuf);
 
@@ -83,7 +88,7 @@ void vRingbufferDelete(RingbufHandle_t ringbuf);
 /**
  * @brief  Get maximum size of an item that can be placed in the ring buffer
  *
- * @param  ringbuf - Ring buffer to query
+ * @param  ringbuf  Ring buffer to query
  *
  * @return Maximum size, in bytes, of an item that can be placed in a ring buffer.
  */
@@ -93,13 +98,15 @@ size_t xRingbufferGetMaxItemSize(RingbufHandle_t ringbuf);
 /**
  * @brief  Insert an item into the ring buffer
  *
- * @param  ringbuf - Ring buffer to insert the item into
- * @param  data - Pointer to data to insert. NULL is allowed if data_size is 0.
- * @param  data_size - Size of data to insert. A value of 0 is allowed.
- * @param  xTicksToWait - Ticks to wait for room in the ringbuffer.
+ * @param  ringbuf  Ring buffer to insert the item into
+ * @param  data  Pointer to data to insert. NULL is allowed if data_size is 0.
+ * @param  data_size  Size of data to insert. A value of 0 is allowed.
+ * @param  ticks_to_wait  Ticks to wait for room in the ringbuffer.
  *
- * @return pdTRUE if succeeded, pdFALSE on time-out or when the buffer is larger 
- *         than indicated by xRingbufferGetMaxItemSize(ringbuf).
+ * @return
+ *      - pdTRUE if succeeded
+ *      - pdFALSE on time-out or when the buffer is larger than indicated
+ *        by xRingbufferGetMaxItemSize(ringbuf).
  */
 BaseType_t xRingbufferSend(RingbufHandle_t ringbuf, void *data, size_t data_size, TickType_t ticks_to_wait);
 
@@ -107,11 +114,11 @@ BaseType_t xRingbufferSend(RingbufHandle_t ringbuf, void *data, size_t data_size
 /**
  * @brief  Insert an item into the ring buffer from an ISR
  *
- * @param  ringbuf - Ring buffer to insert the item into
- * @param  data - Pointer to data to insert. NULL is allowed if data_size is 0.
- * @param  data_size - Size of data to insert. A value of 0 is allowed.
- * @param  higher_prio_task_awoken - Value pointed to will be set to pdTRUE if the push woke up a higher
- *                                     priority task.
+ * @param  ringbuf  Ring buffer to insert the item into
+ * @param  data  Pointer to data to insert. NULL is allowed if data_size is 0.
+ * @param  data_size  Size of data to insert. A value of 0 is allowed.
+ * @param[out]  higher_prio_task_awoken  Value pointed to will be set to pdTRUE
+ *                                  if the push woke up a higher priority task.
  *
  * @return pdTRUE if succeeded, pdFALSE when the ring buffer does not have space.
  */
@@ -120,14 +127,18 @@ BaseType_t xRingbufferSendFromISR(RingbufHandle_t ringbuf, void *data, size_t da
 /**
  * @brief  Retrieve an item from the ring buffer
  *
- * @note A call to vRingbufferReturnItem() is required after this to free up the data received.
+ * @note A call to vRingbufferReturnItem() is required after this to free up
+ * the data received.
  *
- * @param  ringbuf - Ring buffer to retrieve the item from
- * @param  item_size - Pointer to a variable to which the size of the retrieved item will be written.
- * @param  xTicksToWait - Ticks to wait for items in the ringbuffer.
+ * @param  ringbuf  Ring buffer to retrieve the item from
+ * @param[out] item_size  Pointer to a variable to which the size of the
+ *                        retrieved item will be written.
+ * @param  ticks_to_wait  Ticks to wait for items in the ringbuffer.
  *
- * @return Pointer to the retrieved item on success; *item_size filled with the length of the 
- *         item. NULL on timeout, *item_size is untouched in that case.
+ * @return
+ *      - pointer to the retrieved item on success; *item_size filled with
+ *        the length of the item.
+ *      - NULL on timeout, *item_size is untouched in that case.
  */
 void *xRingbufferReceive(RingbufHandle_t ringbuf, size_t *item_size, TickType_t ticks_to_wait);
 
@@ -135,44 +146,58 @@ void *xRingbufferReceive(RingbufHandle_t ringbuf, size_t *item_size, TickType_t
 /**
  * @brief  Retrieve an item from the ring buffer from an ISR
  *
- * @note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received
+ * @note A call to vRingbufferReturnItemFromISR() is required after this to
+ * free up the data received
  *
- * @param  ringbuf - Ring buffer to retrieve the item from
- * @param  item_size - Pointer to a variable to which the size of the retrieved item will be written.
+ * @param  ringbuf  Ring buffer to retrieve the item from
+ * @param[out] item_size  Pointer to a variable to which the size of the
+ *                        retrieved item will be written.
  *
- * @return Pointer to the retrieved item on success; *item_size filled with the length of the 
- *         item. NULL when the ringbuffer is empty, *item_size is untouched in that case.
+ * @return
+ *      - Pointer to the retrieved item on success; *item_size filled with
+ *        the length of the item.
+ *      - NULL when the ringbuffer is empty, *item_size is untouched in that case.
  */
 void *xRingbufferReceiveFromISR(RingbufHandle_t ringbuf, size_t *item_size);
 
 
 /**
- * @brief  Retrieve bytes from a ByteBuf type of ring buffer, specifying the maximum amount of bytes
- * to return
-
- * @note A call to vRingbufferReturnItem() is required after this to free up the data received.
- *
- * @param  ringbuf - Ring buffer to retrieve the item from
- * @param  item_size - Pointer to a variable to which the size of the retrieved item will be written.
- * @param  xTicksToWait - Ticks to wait for items in the ringbuffer.
- *
- * @return Pointer to the retrieved item on success; *item_size filled with the length of the 
- *         item. NULL on timeout, *item_size is untouched in that case.
+ * @brief  Retrieve bytes from a ByteBuf type of ring buffer,
+ * specifying the maximum amount of bytes to return
+ *
+ * @note A call to vRingbufferReturnItem() is required after this to free up
+ * the data received.
+ *
+ * @param  ringbuf  Ring buffer to retrieve the item from
+ * @param[out] item_size  Pointer to a variable to which the size
+ *                        of the retrieved item will be written.
+ * @param  ticks_to_wait  Ticks to wait for items in the ringbuffer.
+ * @param  wanted_size  Maximum number of bytes to return.
+ *
+ * @return
+ *      - Pointer to the retrieved item on success; *item_size filled with
+ *        the length of the item.
+ *      - NULL on timeout, *item_size is untouched in that case.
  */
 void *xRingbufferReceiveUpTo(RingbufHandle_t ringbuf, size_t *item_size, TickType_t ticks_to_wait, size_t wanted_size);
 
 
 /**
- * @brief  Retrieve bytes from a ByteBuf type of ring buffer, specifying the maximum amount of bytes
- * to return. Call this from an ISR.
+ * @brief  Retrieve bytes from a ByteBuf type of ring buffer,
+ * specifying the maximum amount of bytes to return. Call this from an ISR.
  *
- * @note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received
+ * @note A call to vRingbufferReturnItemFromISR() is required after this
+ * to free up the data received.
  *
- * @param  ringbuf - Ring buffer to retrieve the item from
- * @param  item_size - Pointer to a variable to which the size of the retrieved item will be written.
+ * @param  ringbuf  Ring buffer to retrieve the item from
+ * @param[out] item_size  Pointer to a variable to which the size of the
+ *                        retrieved item will be written.
+ * @param  wanted_size  Maximum number of bytes to return.
  *
- * @return Pointer to the retrieved item on success; *item_size filled with the length of the 
- *         item. NULL when the ringbuffer is empty, *item_size is untouched in that case.
+ * @return
+ *      - Pointer to the retrieved item on success; *item_size filled with
+ *        the length of the item.
+ *      - NULL when the ringbuffer is empty, *item_size is untouched in that case.
  */
 void *xRingbufferReceiveUpToFromISR(RingbufHandle_t ringbuf, size_t *item_size, size_t wanted_size);
 
@@ -181,10 +206,8 @@ void *xRingbufferReceiveUpToFromISR(RingbufHandle_t ringbuf, size_t *item_size,
 /**
  * @brief  Return a previously-retrieved item to the ringbuffer
  *
- * @param  ringbuf - Ring buffer the item was retrieved from
- * @param  item - Item that was received earlier
- *
- * @return void
+ * @param  ringbuf  Ring buffer the item was retrieved from
+ * @param  item  Item that was received earlier
  */
 void vRingbufferReturnItem(RingbufHandle_t ringbuf, void *item);
 
@@ -193,34 +216,37 @@ void vRingbufferReturnItem(RingbufHandle_t ringbuf, void *item);
 /**
  * @brief  Return a previously-retrieved item to the ringbuffer from an ISR
  *
- * @param  ringbuf - Ring buffer the item was retrieved from
- * @param  item - Item that was received earlier
- * @param  higher_prio_task_awoken - Value pointed to will be set to pdTRUE if the push woke up a higher
- *                                     priority task.
- *
- * @return void
+ * @param  ringbuf  Ring buffer the item was retrieved from
+ * @param  item  Item that was received earlier
+ * @param[out]  higher_prio_task_awoken  Value pointed to will be set to pdTRUE
+ *                                  if the push woke up a higher priority task.
  */
 void vRingbufferReturnItemFromISR(RingbufHandle_t ringbuf, void *item, BaseType_t *higher_prio_task_awoken);
 
 
 /**
- * @brief  Add the ringbuffer to a queue set. This specifically adds the semaphore that indicates
- *         more space has become available in the ringbuffer.
+ * @brief  Add the ringbuffer to a queue set.
  *
- * @param  ringbuf - Ring buffer to add to the queue set
- * @param  xQueueSet - Queue set to add the ringbuffer to
+ * This specifically adds the semaphore that indicates more space
+ * has become available in the ringbuffer.
  *
- * @return pdTRUE on success, pdFALSE otherwise
+ * @param  ringbuf  Ring buffer to add to the queue set
+ * @param  xQueueSet  Queue set to add the ringbuffer to
+ *
+ * @return
+ *      - pdTRUE on success, pdFALSE otherwise
  */
 BaseType_t xRingbufferAddToQueueSetRead(RingbufHandle_t ringbuf, QueueSetHandle_t xQueueSet);
 
 
 /**
- * @brief  Add the ringbuffer to a queue set. This specifically adds the semaphore that indicates
- *         something has been written into the ringbuffer.
+ * @brief  Add the ringbuffer to a queue set.
  *
- * @param  ringbuf - Ring buffer to add to the queue set
- * @param  xQueueSet - Queue set to add the ringbuffer to
+ * This specifically adds the semaphore that indicates something has been
+ * written into the ringbuffer.
+ *
+ * @param  ringbuf  Ring buffer to add to the queue set
+ * @param  xQueueSet  Queue set to add the ringbuffer to
  *
  * @return pdTRUE on success, pdFALSE otherwise
  */
@@ -228,11 +254,13 @@ BaseType_t xRingbufferAddToQueueSetWrite(RingbufHandle_t ringbuf, QueueSetHandle
 
 
 /**
- * @brief  Remove the ringbuffer from a queue set. This specifically removes the semaphore that indicates
- *         more space has become available in the ringbuffer.
+ * @brief  Remove the ringbuffer from a queue set.
+ *
+ * This specifically removes the semaphore that indicates more space
+ * has become available in the ringbuffer.
  *
- * @param  ringbuf - Ring buffer to remove from the queue set
- * @param  xQueueSet - Queue set to remove the ringbuffer from
+ * @param  ringbuf  Ring buffer to remove from the queue set
+ * @param  xQueueSet  Queue set to remove the ringbuffer from
  *
  * @return pdTRUE on success, pdFALSE otherwise
  */
@@ -240,11 +268,13 @@ BaseType_t xRingbufferRemoveFromQueueSetRead(RingbufHandle_t ringbuf, QueueSetHa
 
 
 /**
- * @brief  Remove the ringbuffer from a queue set. This specifically removes the semaphore that indicates
- *         something has been written to the ringbuffer.
+ * @brief  Remove the ringbuffer from a queue set.
  *
- * @param  ringbuf - Ring buffer to remove from the queue set
- * @param  xQueueSet - Queue set to remove the ringbuffer from
+ * This specifically removes the semaphore that indicates something
+ * has been written to the ringbuffer.
+ *
+ * @param  ringbuf  Ring buffer to remove from the queue set
+ * @param  xQueueSet  Queue set to remove the ringbuffer from
  *
  * @return pdTRUE on success, pdFALSE otherwise
  */
@@ -254,9 +284,7 @@ BaseType_t xRingbufferRemoveFromQueueSetWrite(RingbufHandle_t ringbuf, QueueSetH
 /**
  * @brief  Debugging function to print the internal pointers in the ring buffer
  *
- * @param  ringbuf - Ring buffer to show
- *
- * @return void
+ * @param  ringbuf  Ring buffer to show
  */
 void xRingbufferPrintInfo(RingbufHandle_t ringbuf);
 

components/freertos/include/freertos/timers.h

@@ -117,24 +117,18 @@ or interrupt version of the queue send function should be used. */
  */
 typedef void * TimerHandle_t;
 
-/*
+/**
  * Defines the prototype to which timer callback functions must conform.
  */
 typedef void (*TimerCallbackFunction_t)( TimerHandle_t xTimer );
 
-/*
+/**
  * Defines the prototype to which functions used with the
  * xTimerPendFunctionCallFromISR() function must conform.
  */
 typedef void (*PendedFunction_t)( void *, uint32_t );
 
 /**
- * TimerHandle_t xTimerCreate( 	const char * const pcTimerName,
- * 								TickType_t xTimerPeriodInTicks,
- * 								UBaseType_t uxAutoReload,
- * 								void * pvTimerID,
- * 								TimerCallbackFunction_t pxCallbackFunction );
- *
  * Creates a new software timer instance, and returns a handle by which the
  * created software timer can be referenced.
  *
@@ -184,7 +178,7 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
  * structures, or the timer period was set to 0) then NULL is returned.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  * #define NUM_TIMERS 5
  *
  * // An array to hold handles to the created timers.
@@ -263,7 +257,7 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
  *     // Should not reach here.
  *     for( ;; );
  * }
- * @endverbatim
+ * @endcode
  */
 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 	TimerHandle_t xTimerCreate(	const char * const pcTimerName,
@@ -274,13 +268,6 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
 #endif
 
  /**
-  * TimerHandle_t xTimerCreateStatic(const char * const pcTimerName,
-  * 									TickType_t xTimerPeriodInTicks,
-  * 									UBaseType_t uxAutoReload,
-  * 									void * pvTimerID,
-  * 									TimerCallbackFunction_t pxCallbackFunction,
-  *									StaticTimer_t *pxTimerBuffer );
-  *
   * Creates a new software timer instance, and returns a handle by which the
   * created software timer can be referenced.
   *
@@ -332,7 +319,7 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
   * returned.  If pxTimerBuffer was NULL then NULL is returned.
   *
   * Example usage:
-  * @verbatim
+  * @code{c}
   *
   * // The buffer used to hold the software timer's data structure.
   * static StaticTimer_t xTimerBuffer;
@@ -393,20 +380,18 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
   *     // Should not reach here.
   *     for( ;; );
   * }
-  * @endverbatim
+  * @endcode
   */
  #if( configSUPPORT_STATIC_ALLOCATION == 1 )
- 	TimerHandle_t xTimerCreateStatic(	const char * const pcTimerName,
- 										const TickType_t xTimerPeriodInTicks,
- 										const UBaseType_t uxAutoReload,
- 										void * const pvTimerID,
- 										TimerCallbackFunction_t pxCallbackFunction,
- 										StaticTimer_t *pxTimerBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
+	TimerHandle_t xTimerCreateStatic(	const char * const pcTimerName,
+										const TickType_t xTimerPeriodInTicks,
+										const UBaseType_t uxAutoReload,
+										void * const pvTimerID,
+										TimerCallbackFunction_t pxCallbackFunction,
+										StaticTimer_t *pxTimerBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
  #endif /* configSUPPORT_STATIC_ALLOCATION */
 
 /**
- * void *pvTimerGetTimerID( TimerHandle_t xTimer );
- *
  * Returns the ID assigned to the timer.
  *
  * IDs are assigned to timers using the pvTimerID parameter of the call to
@@ -427,8 +412,6 @@ typedef void (*PendedFunction_t)( void *, uint32_t );
 void *pvTimerGetTimerID( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 
 /**
- * void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );
- *
  * Sets the ID assigned to the timer.
  *
  * IDs are assigned to timers using the pvTimerID parameter of the call to
@@ -448,12 +431,12 @@ void *pvTimerGetTimerID( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION;
 
 /**
- * BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );
- *
  * Queries a timer to see if it is active or dormant.
  *
  * A timer will be dormant if:
+ *
  *     1) It has been created but not started, or
+ *
  *     2) It is an expired one-shot timer that has not been restarted.
  *
  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),
@@ -467,7 +450,7 @@ void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION
  * pdFALSE will be returned if the timer is active.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  * // This function assumes xTimer has already been created.
  * void vAFunction( TimerHandle_t xTimer )
  * {
@@ -480,13 +463,11 @@ void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION
  *         // xTimer is not active, do something else.
  *     }
  * }
- * @endverbatim
+ * @endcode
  */
 BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 
 /**
- * TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
- *
  * xTimerGetTimerDaemonTaskHandle() is only available if
  * INCLUDE_xTimerGetTimerDaemonTaskHandle is set to 1 in FreeRTOSConfig.h.
  *
@@ -496,8 +477,6 @@ BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
 
 /**
- * TickType_t xTimerGetPeriod( TimerHandle_t xTimer );
- *
  * Returns the period of a timer.
  *
  * @param xTimer The handle of the timer being queried.
@@ -507,8 +486,6 @@ TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
 TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 
 /**
- * TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );
- *
  * Returns the time in ticks at which the timer will expire.  If this is less
  * than the current tick count then the expiry time has overflowed from the
  * current time.
@@ -522,8 +499,6 @@ TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 
 /**
- * BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
- *
  * Timer functionality is provided by a timer service/daemon task.  Many of the
  * public FreeRTOS timer API functions send commands to the timer service task
  * through a queue called the timer command queue.  The timer command queue is
@@ -574,8 +549,6 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 #define xTimerStart( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
 
 /**
- * BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );
- *
  * Timer functionality is provided by a timer service/daemon task.  Many of the
  * public FreeRTOS timer API functions send commands to the timer service task
  * through a queue called the timer command queue.  The timer command queue is
@@ -616,10 +589,6 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 #define xTimerStop( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xTicksToWait ) )
 
 /**
- * BaseType_t xTimerChangePeriod( 	TimerHandle_t xTimer,
- *										TickType_t xNewPeriod,
- *										TickType_t xTicksToWait );
- *
  * Timer functionality is provided by a timer service/daemon task.  Many of the
  * public FreeRTOS timer API functions send commands to the timer service task
  * through a queue called the timer command queue.  The timer command queue is
@@ -661,7 +630,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  * configTIMER_TASK_PRIORITY configuration constant.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  * // This function assumes xTimer has already been created.  If the timer
  * // referenced by xTimer is already active when it is called, then the timer
  * // is deleted.  If the timer referenced by xTimer is not active when it is
@@ -691,13 +660,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  *         }
  *     }
  * }
- * @endverbatim
+ * @endcode
  */
  #define xTimerChangePeriod( xTimer, xNewPeriod, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xTicksToWait ) )
 
 /**
- * BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );
- *
  * Timer functionality is provided by a timer service/daemon task.  Many of the
  * public FreeRTOS timer API functions send commands to the timer service task
  * through a queue called the timer command queue.  The timer command queue is
@@ -734,8 +701,6 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
 #define xTimerDelete( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xTicksToWait ) )
 
 /**
- * BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
- *
  * Timer functionality is provided by a timer service/daemon task.  Many of the
  * public FreeRTOS timer API functions send commands to the timer service task
  * through a queue called the timer command queue.  The timer command queue is
@@ -781,7 +746,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  * configuration constant.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  * // When a key is pressed, an LCD back-light is switched on.  If 5 seconds pass
  * // without a key being pressed, then the LCD back-light is switched off.  In
  * // this case, the timer is a one-shot timer.
@@ -853,14 +818,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  *     // Should not reach here.
  *     for( ;; );
  * }
- * @endverbatim
+ * @endcode
  */
 #define xTimerReset( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
 
 /**
- * BaseType_t xTimerStartFromISR( 	TimerHandle_t xTimer,
- *									BaseType_t *pxHigherPriorityTaskWoken );
- *
  * A version of xTimerStart() that can be called from an interrupt service
  * routine.
  *
@@ -888,7 +850,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  * configuration constant.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  * // This scenario assumes xBacklightTimer has already been created.  When a
  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass
  * // without a key being pressed, then the LCD back-light is switched off.  In
@@ -939,14 +901,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  *         // depends on the FreeRTOS port being used).
  *     }
  * }
- * @endverbatim
+ * @endcode
  */
 #define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
 
 /**
- * BaseType_t xTimerStopFromISR( 	TimerHandle_t xTimer,
- *									BaseType_t *pxHigherPriorityTaskWoken );
- *
  * A version of xTimerStop() that can be called from an interrupt service
  * routine.
  *
@@ -972,7 +931,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  * // This scenario assumes xTimer has already been created and started.  When
  * // an interrupt occurs, the timer should be simply stopped.
  *
@@ -1002,15 +961,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  *         // depends on the FreeRTOS port being used).
  *     }
  * }
- * @endverbatim
+ * @endcode
  */
 #define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U )
 
 /**
- * BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer,
- *										 TickType_t xNewPeriod,
- *										 BaseType_t *pxHigherPriorityTaskWoken );
- *
  * A version of xTimerChangePeriod() that can be called from an interrupt
  * service routine.
  *
@@ -1045,7 +1000,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  * // This scenario assumes xTimer has already been created and started.  When
  * // an interrupt occurs, the period of xTimer should be changed to 500ms.
  *
@@ -1075,14 +1030,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  *         // depends on the FreeRTOS port being used).
  *     }
  * }
- * @endverbatim
+ * @endcode
  */
 #define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )
 
 /**
- * BaseType_t xTimerResetFromISR( 	TimerHandle_t xTimer,
- *									BaseType_t *pxHigherPriorityTaskWoken );
- *
  * A version of xTimerReset() that can be called from an interrupt service
  * routine.
  *
@@ -1110,7 +1062,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  * task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  * // This scenario assumes xBacklightTimer has already been created.  When a
  * // key is pressed, an LCD back-light is switched on.  If 5 seconds pass
  * // without a key being pressed, then the LCD back-light is switched off.  In
@@ -1161,18 +1113,12 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  *         // depends on the FreeRTOS port being used).
  *     }
  * }
- * @endverbatim
+ * @endcode
  */
 #define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
 
 
 /**
- * BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,
- *                                          void *pvParameter1,
- *                                          uint32_t ulParameter2,
- *                                          BaseType_t *pxHigherPriorityTaskWoken );
- *
- *
  * Used from application interrupt service routines to defer the execution of a
  * function to the RTOS daemon task (the timer service task, hence this function
  * is implemented in timers.c and is prefixed with 'Timer').
@@ -1214,7 +1160,7 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  * timer daemon task, otherwise pdFALSE is returned.
  *
  * Example usage:
- * @verbatim
+ * @code{c}
  *
  *	// The callback function that will execute in the context of the daemon task.
  *  // Note callback functions must all use this same prototype.
@@ -1252,17 +1198,11 @@ TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
  *		portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
  *
  *	}
- * @endverbatim
+ * @endcode
  */
 BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken );
 
  /**
-  * BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,
-  *                                    void *pvParameter1,
-  *                                    uint32_t ulParameter2,
-  *                                    TickType_t xTicksToWait );
-  *
-  *
   * Used to defer the execution of a function to the RTOS daemon task (the timer
   * service task, hence this function is implemented in timers.c and is prefixed
   * with 'Timer').
@@ -1291,8 +1231,6 @@ BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void
 BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait );
 
 /**
- * const char * const pcTimerGetTimerName( TimerHandle_t xTimer );
- *
  * Returns the name that was assigned to a timer when the timer was created.
  *
  * @param xTimer The handle of the timer being queried.
@@ -1301,6 +1239,7 @@ BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvPar
  */
 const char * pcTimerGetTimerName( TimerHandle_t xTimer ); /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
 
+/** @cond */
 /*
  * Functions beyond this part are not part of the public API and are intended
  * for use by the kernel only.
@@ -1308,6 +1247,8 @@ const char * pcTimerGetTimerName( TimerHandle_t xTimer ); /*lint !e971 Unqualifi
 BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;
 BaseType_t xTimerGenericCommand( TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t * const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
 
+/** @endcond */
+
 #ifdef __cplusplus
 }
 #endif

docs/Doxyfile

@@ -153,7 +153,17 @@ INPUT = \
     ../components/esp32/include/esp_pm.h \
     ../components/esp32/include/esp32/pm.h \
     ### esp_timer, High Resolution Timer
-    ../components/esp32/include/esp_timer.h
+    ../components/esp32/include/esp_timer.h \
+    ###
+    ### FreeRTOS
+    ###
+    ../components/freertos/include/freertos/task.h \
+    ../components/freertos/include/freertos/queue.h \
+    ../components/freertos/include/freertos/semphr.h \
+    ../components/freertos/include/freertos/timers.h \
+    ../components/freertos/include/freertos/event_groups.h \
+    ../components/freertos/include/freertos/ringbuf.h
+
 
 
 ## Get warnings for functions that have no documentation for their parameters or return value
@@ -165,7 +175,16 @@ WARN_NO_PARAMDOC = YES
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
-PREDEFINED             = __attribute__(x)=
+PREDEFINED             = \
+    __attribute__(x)= \
+    IRAM_ATTR= \
+    configSUPPORT_DYNAMIC_ALLOCATION=1 \
+    configSUPPORT_STATIC_ALLOCATION=1 \
+    configQUEUE_REGISTRY_SIZE=1 \
+    configUSE_RECURSIVE_MUTEXES=1 \
+    configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS=1 \
+    configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \
+    configUSE_APPLICATION_TASK_TAG=1
 
 ## Do not complain about not having dot
 ##

docs/api-reference/system/freertos.rst

@@ -0,0 +1,42 @@
+FreeRTOS
+========
+
+Overview
+--------
+
+This section contains documentation of FreeRTOS types, functions, and macros. It is automatically generated from FreeRTOS header files.
+
+For more information about FreeRTOS features specific to ESP-IDF, see :doc:`ESP-IDF FreeRTOS SMP Changes<../../api-guides/freertos-smp>`.
+
+
+Task API
+--------
+
+.. include:: /_build/inc/task.inc
+
+Queue API
+---------
+
+.. include:: /_build/inc/queue.inc
+
+Semaphore API
+-------------
+
+.. include:: /_build/inc/semphr.inc
+
+Timer API
+---------
+
+.. include:: /_build/inc/timers.inc
+
+
+Event Group API
+---------------
+
+.. include:: /_build/inc/event_groups.inc
+
+Ringbuffer API
+--------------
+
+.. include:: /_build/inc/ringbuf.inc
+

docs/api-reference/system/hooks.rst

@@ -1,7 +1,7 @@
 .. _hooks_api_reference:
 
-ESP-IDF FreeRTOS Hooks
-======================
+FreeRTOS Hooks
+==============
 
 Overview
 --------

docs/api-reference/system/index.rst

@@ -4,19 +4,20 @@ System API
 .. toctree::
    :maxdepth: 1
 
+   FreeRTOS <freertos>
+   FreeRTOS Hooks <hooks>
    Heap Memory Allocation <mem_alloc>
    Heap Memory Debugging <heap_debug>
    Interrupt Allocation <intr_alloc>
    Watchdogs <wdts>
-   Hooks <hooks>
    Inter-Processor Call <ipc>
    High Resolution Timer <esp_timer>
-   Over The Air Updates (OTA) <ota>
-   Sleep Modes <sleep_modes>
-   Power Management <power_management>
    Logging <log>
-   Base MAC address <base_mac_address>
    Application Level Tracing <app_trace>
+   Power Management <power_management>
+   Sleep Modes <sleep_modes>
+   Base MAC address <base_mac_address>
+   Over The Air Updates (OTA) <ota>
 
 
 Example code for this API section is provided in :example:`system` directory of ESP-IDF examples.