score: Document Thread_Life_state

1 files changed, 40 insertions, 3 deletions

diff --git a/cpukit/include/rtems/score/thread.h b/cpukit/include/rtems/score/thread.h
index 8785879184..e8252b364f 100644
--- a/cpukit/include/rtems/score/thread.h
+++ b/cpukit/include/rtems/score/thread.h
@@ -659,20 +659,57 @@ typedef struct {
 } Thread_Action_control;
 
 /**
- * @brief Thread life states.
+ * @brief This type represents the thread life state.
  *
- * The thread life states are orthogonal to the thread states used for
+ * The thread life state is orthogonal to the thread state used for
  * synchronization primitives and blocking operations.  They reflect the state
  * changes triggered with thread restart and delete requests.
  *
- * The individual state values must be a power of two to allow use of bit
+ * The individual state flags must be a power of two to allow use of bit
  * operations to manipulate and evaluate the thread life state.
  */
 typedef enum {
+  /**
+   * @brief Indicates that the thread life is protected.
+   *
+   * If this flag is set, then the thread restart or delete requests are deferred
+   * until the protection and deferred change flags are cleared.  It is used by
+   * _Thread_Set_life_protection().
+   */
   THREAD_LIFE_PROTECTED = 0x1,
+
+  /**
+   * @brief Indicates that thread is restarting.
+   *
+   * If this flag is set, then a thread restart request is in pending. See
+   * _Thread_Restart_self() and _Thread_Restart_other().
+   */
   THREAD_LIFE_RESTARTING = 0x2,
+
+  /**
+   * @brief Indicates that thread is terminating.
+   *
+   * If this flag is set, then a thread termination request is in pending.  See
+   * _Thread_Exit() and _Thread_Cancel().
+   */
   THREAD_LIFE_TERMINATING = 0x4,
+
+  /**
+   * @brief Indicates that thread life changes are deferred.
+   *
+   * If this flag is set, then the thread restart or delete requests are deferred
+   * until the protection and deferred change flags are cleared.  It is used by
+   * pthread_setcanceltype().
+   */
   THREAD_LIFE_CHANGE_DEFERRED = 0x8,
+
+  /**
+   * @brief Indicates that thread is detached.
+   *
+   * If this flag is set, then the thread is detached.  Detached threads do not
+   * wait during termination for other threads to join.  See rtems_task_delete(),
+   * rtems_task_exit(), and pthread_detach().
+   */
   THREAD_LIFE_DETACHED = 0x10
 } Thread_Life_state;