Tidy up timers API documentation comments.

git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@1318 1d2547de-c912-0410-9cb9-b8ca96c0e9e2

diff --git a/Source/include/timers.h b/Source/include/timers.h
index 34a20663183caeb9ecb7a22c51cf29f5cc7ba9e9..727c4fdecb219b2e11c3d492999f2fa38e8b07bf 100644 (file)
--- a/Source/include/timers.h
+++ b/Source/include/timers.h
@@ -102,7 +102,7 @@ typedef void (*tmrTIMER_CALLBACK)( xTimerHandle xTimer );
  *\r
  * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),\r
  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and\r
- * xTimerChangePeriodFromISR() can all be used to transition a timer into the\r
+ * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the\r
  * active state.\r
  *\r
  * @param pcTimerName A text name that is assigned to the timer.  This is done\r
@@ -114,19 +114,21 @@ typedef void (*tmrTIMER_CALLBACK)( xTimerHandle xTimer );
  * specified in milliseconds.  For example, if the timer must expire after 100\r
  * ticks, then xTimerPeriod should be set to 100.  Alternatively, if the timer\r
  * must expire after 500ms, then xPeriod can be set to ( 500 / portTICK_RATE_MS )\r
- * provided configTICK_RATE_HZ is set to less than or equal to 1000.\r
+ * provided configTICK_RATE_HZ is less than or equal to 1000.\r
  *\r
  * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will\r
  * expire repeatedly with a frequency set by the xTimerPeriod parameter.  If\r
  * uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and\r
- * will expire once only xTimerPeriod ticks from the time it is started.\r
+ * enter the dormant state after it expires.\r
  *\r
- * @param pvTimerID An identifier to assign to the timer being created.  \r
- * Typically this would be used to identify the timer that expired within the\r
- * timers callback function when multiple timers are assigned the same callback\r
- * function.\r
+ * @param pvTimerID An identifier that is assigned to the timer being created.  \r
+ * Typically this would be used in the timer callback function to identify which \r
+ * timer expired when the same callback function is assigned to more than one \r
+ * timer.\r
  *\r
  * @param pxCallbackFunction The function to call when the timer expires.\r
+ * Callback functions must have the prototype defined by tmrTIMER_CALLBACK, \r
+ * which is    "void vCallbackFunction( xTIMER *xTimer );".\r
  *\r
  * @return If the timer is successfully create then a handle to the newly\r
  * created timer is returned.  If the timer cannot be created (because either\r
@@ -220,12 +222,12 @@ xTimerHandle xTimerCreate( const signed char *pcTimerName, portTickType xTimerPe
 /**\r
  * void *pvTimerGetTimerID( xTimerHandle xTimer );\r
  *\r
- * Returns the ID assigned to the xTimer parameter.  \r
+ * Returns the ID assigned to the timer.\r
  * \r
  * IDs are assigned to timers using the pvTimerID parameter of the call to\r
- * xTimerCreated() used to create the timer.\r
+ * xTimerCreated() that was used to create the timer.\r
  *\r
- * If the same callback function is assigned to multiple tasks then the timer\r
+ * If the same callback function is assigned to multiple timers then the timer\r
  * ID can be used within the callback function to identify which timer actually\r
  * expired.\r
  *\r
@@ -248,9 +250,10 @@ void *pvTimerGetTimerID( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *     1) It has been created but not started, or \r
  *     2) It is an expired on-shot timer that has not been restarted.\r
  *\r
- * Timers can be started using the xTimerStart(), xTimerReset(),\r
+ * Timers are created in the dormant state.  The xTimerStart(), xTimerReset(),\r
  * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and\r
- * xTimerChangePeriodFromISR() API functions.\r
+ * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the\r
+ * active state.\r
  *\r
  * @param xTimer The timer being queried.\r
  *\r
@@ -262,7 +265,7 @@ void *pvTimerGetTimerID( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  * // This function assumes xTimer has already been created.\r
  * void vAFunction( xTimerHandle xTimer )\r
  * {\r
- *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer )" )\r
+ *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"\r
  *     {\r
  *         // xTimer is active, do something.\r
  *     }\r
@@ -291,7 +294,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * Starting a timer ensures the timer is in the active state.  If the timer\r
  * is not stopped, deleted, or reset in the mean time, the callback function\r
- * associated with the timer will get called 'n 'ticks after xTimerStart() was \r
+ * associated with the timer will get called 'n' ticks after xTimerStart() was \r
  * called, where 'n' is the timers defined period.\r
  *\r
  * It is valid to call xTimerStart() before the scheduler has been started, but\r
@@ -312,7 +315,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the start command could not be sent to \r
  * the timer command queue even after xBlockTime ticks had passed.  pdPASS will\r
- * be returned if the command was successfully send to the timer command queue.\r
+ * be returned if the command was successfully sent to the timer command queue.\r
  * When the command is actually processed will depend on the priority of the\r
  * timer service/daemon task relative to other tasks in the system, although the\r
  * timers expiry time is relative to when xTimerStart() is actually called.  The \r
@@ -355,7 +358,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the stop command could not be sent to \r
  * the timer command queue even after xBlockTime ticks had passed.  pdPASS will\r
- * be returned if the command was successfully send to the timer command queue.\r
+ * be returned if the command was successfully sent to the timer command queue.\r
  * When the command is actually processed will depend on the priority of the\r
  * timer service/daemon task relative to other tasks in the system.  The timer \r
  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY \r
@@ -396,7 +399,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  * that has been specified in milliseconds.  For example, if the timer must \r
  * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively, \r
  * if the timer must expire after 500ms, then xNewPeriod can be set to \r
- * ( 500 / portTICK_RATE_MS ) provided configTICK_RATE_HZ is set to less than\r
+ * ( 500 / portTICK_RATE_MS ) provided configTICK_RATE_HZ is less than\r
  * or equal to 1000.\r
  *\r
  * @param xBlockTime Specifies the time, in ticks, that the calling task should\r
@@ -407,7 +410,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the change period command could not be \r
  * sent to the timer command queue even after xBlockTime ticks had passed.  \r
- * pdPASS will be returned if the command was successfully send to the timer \r
+ * pdPASS will be returned if the command was successfully sent to the timer \r
  * command queue.  When the command is actually processed will depend on the \r
  * priority of the timer service/daemon task relative to other tasks in the \r
  * system.  The timer service/daemon task priority is set by the \r
@@ -422,7 +425,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  * // started.\r
  * void vAFunction( xTimerHandle xTimer )\r
  * {\r
- *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer )" )\r
+ *     if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"\r
  *     {\r
  *         // xTimer is already active - delete it.\r
  *         xTimerDelete( xTimer );\r
@@ -441,7 +444,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *         {\r
  *             // The command could not be sent, even after waiting for 100 ticks\r
  *             // to pass.  Take appropriate action here.\r
- *         {\r
+ *         }\r
  *     } \r
  * }\r
  */\r
@@ -463,7 +466,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  * The configUSE_TIMERS configuration constant must be set to 1 for \r
  * xTimerDelete() to be available.\r
  *\r
- * @param xTimer The handle of the timer being stopped.\r
+ * @param xTimer The handle of the timer being deleted.\r
  *\r
  * @param xBlockTime Specifies the time, in ticks, that the calling task should\r
  * be held in the Blocked state to wait for the delete command to be \r
@@ -473,7 +476,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the delete command could not be sent to \r
  * the timer command queue even after xBlockTime ticks had passed.  pdPASS will\r
- * be returned if the command was successfully send to the timer command queue.\r
+ * be returned if the command was successfully sent to the timer command queue.\r
  * When the command is actually processed will depend on the priority of the\r
  * timer service/daemon task relative to other tasks in the system.  The timer \r
  * service/daemon task priority is set by the configTIMER_TASK_PRIORITY \r
@@ -504,7 +507,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * Resetting a timer ensures the timer is in the active state.  If the timer\r
  * is not stopped, deleted, or reset in the mean time, the callback function\r
- * associated with the timer will get called 'n 'ticks after xTimerReset() was \r
+ * associated with the timer will get called 'n' ticks after xTimerReset() was \r
  * called, where 'n' is the timers defined period.\r
  *\r
  * It is valid to call xTimerReset() before the scheduler has been started, but\r
@@ -515,7 +518,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  * The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset()\r
  * to be available.\r
  *\r
- * @param xTimer The handle of the timer being started/restarted.\r
+ * @param xTimer The handle of the timer being reset/started/restarted.\r
  *\r
  * @param xBlockTime Specifies the time, in ticks, that the calling task should\r
  * be held in the Blocked state to wait for the reset command to be successfully\r
@@ -525,7 +528,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the reset command could not be sent to \r
  * the timer command queue even after xBlockTime ticks had passed.  pdPASS will\r
- * be returned if the command was successfully send to the timer command queue.\r
+ * be returned if the command was successfully sent to the timer command queue.\r
  * When the command is actually processed will depend on the priority of the\r
  * timer service/daemon task relative to other tasks in the system, although the\r
  * timers expiry time is relative to when xTimerStart() is actually called.  The \r
@@ -631,10 +634,10 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the start command could not be sent to \r
  * the timer command queue.  pdPASS will be returned if the command was \r
- * successfully send to the timer command queue.  When the command is actually \r
+ * successfully sent to the timer command queue.  When the command is actually \r
  * processed will depend on the priority of the timer service/daemon task \r
  * relative to other tasks in the system, although the timers expiry time is \r
- * relative to when xTimerStart() is actually called.  The timer service/daemon \r
+ * relative to when xTimerStartFromISR() is actually called.  The timer service/daemon \r
  * task priority is set by the configTIMER_TASK_PRIORITY configuration constant. \r
  *\r
  * Example usage:\r
@@ -715,7 +718,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the stop command could not be sent to \r
  * the timer command queue.  pdPASS will be returned if the command was \r
- * successfully send to the timer command queue.  When the command is actually \r
+ * successfully sent to the timer command queue.  When the command is actually \r
  * processed will depend on the priority of the timer service/daemon task \r
  * relative to other tasks in the system.  The timer service/daemon task \r
  * priority is set by the configTIMER_TASK_PRIORITY configuration constant. \r
@@ -764,6 +767,14 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @param xTimer The handle of the timer that is having its period changed.\r
  *\r
+ * @param xNewPeriod The new period for xTimer. Timer periods are specified in \r
+ * tick periods, so the constant portTICK_RATE_MS can be used to convert a time \r
+ * that has been specified in milliseconds.  For example, if the timer must \r
+ * expire after 100 ticks, then xNewPeriod should be set to 100.  Alternatively, \r
+ * if the timer must expire after 500ms, then xNewPeriod can be set to \r
+ * ( 500 / portTICK_RATE_MS ) provided configTICK_RATE_HZ is less than\r
+ * or equal to 1000.\r
+ *\r
  * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most\r
  * of its time in the Blocked state, waiting for messages to arrive on the timer\r
  * command queue.  Calling xTimerChangePeriodFromISR() writes a message to the \r
@@ -779,7 +790,7 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the command to change the timers period\r
  * could not be sent to the timer command queue.  pdPASS will be returned if the \r
- * command was successfully send to the timer command queue.  When the command \r
+ * command was successfully sent to the timer command queue.  When the command \r
  * is actually processed will depend on the priority of the timer service/daemon \r
  * task relative to other tasks in the system.  The timer service/daemon task \r
  * priority is set by the configTIMER_TASK_PRIORITY configuration constant. \r
@@ -842,10 +853,10 @@ portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION;
  *\r
  * @return pdFAIL will be returned if the reset command could not be sent to \r
  * the timer command queue.  pdPASS will be returned if the command was \r
- * successfully send to the timer command queue.  When the command is actually \r
+ * successfully sent to the timer command queue.  When the command is actually \r
  * processed will depend on the priority of the timer service/daemon task \r
  * relative to other tasks in the system, although the timers expiry time is \r
- * relative to when xTimerStart() is actually called.  The timer service/daemon \r
+ * relative to when xTimerResetFromISR() is actually called.  The timer service/daemon \r
  * task priority is set by the configTIMER_TASK_PRIORITY configuration constant. \r
  *\r
  * Example usage:\r