[PATCH] score: Improve Scheduler Handler documentation

[Gedare Bloom]

Thanks, just a couple minor nits.

On Fri, Sep 18, 2020 at 12:38 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> ---
>  cpukit/include/rtems/score/scheduler.h     | 23 ++++++++---------
>  cpukit/include/rtems/score/schedulerimpl.h | 29 +++++++++++++++++++++-
>  2 files changed, 38 insertions(+), 14 deletions(-)
>
> diff --git a/cpukit/include/rtems/score/scheduler.h b/cpukit/include/rtems/score/scheduler.h
> index 9a6515ba1e..4b9936d756 100644
> --- a/cpukit/include/rtems/score/scheduler.h
> +++ b/cpukit/include/rtems/score/scheduler.h
> @@ -30,12 +30,7 @@ extern "C" {
>  struct Per_CPU_Control;
>
>  /**
> - * @defgroup RTEMSScoreScheduler Scheduler Handler
> - *
> - * @ingroup RTEMSScore
> - *
> - * This handler encapsulates functionality related to managing sets of threads
> - * that are ready for execution.
> + * @addtogroup RTEMSScoreScheduler
>   *
>   * @{
>   */
> @@ -300,22 +295,24 @@ struct _Scheduler_Control {
>  };
>
>  /**
> - * @brief Registered schedulers.
> + * @brief This table contains the configured schedulers.
>   *
> - * Application provided via <rtems/confdefs.h>.
> + * The table is defined by <rtems/confdefs.h> through the
> + * #CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option.
>   *
>   * @see _Scheduler_Count.
>   */
>  extern const Scheduler_Control _Scheduler_Table[];
>
>  /**
> - * @brief Count of registered schedulers.
> + * @brief This constant contains the count of configured schedulers.
>   *
> - * Application provided via <rtems/confdefs.h> on SMP configurations.
> + * In SMP configurations, the constant is defined by <rtems/confdefs.h> through
> + * the count of entries of the #CONFIGURE_SCHEDULER_TABLE_ENTRIES application
> + * configuration option.
>   *
> - * It is very important that this is a compile-time constant on uni-processor
> - * configurations (in this case RTEMS_SMP is not defined) so that the compiler
> - * can optimize the some loops away
> + * In uniprocessor configurations, this is a compile time constant set to one.
> + * This is important so that the compiler can optimize the some loops away
s/the some/some
add a period at end.

Not introduced by you, but good to fix.

>   *
>   * @see _Scheduler_Table.
>   */
> diff --git a/cpukit/include/rtems/score/schedulerimpl.h b/cpukit/include/rtems/score/schedulerimpl.h
> index e7fbb8b166..f37d9ecdc8 100644
> --- a/cpukit/include/rtems/score/schedulerimpl.h
> +++ b/cpukit/include/rtems/score/schedulerimpl.h
> @@ -34,7 +34,34 @@ extern "C" {
>  #endif
>
>  /**
> - * @addtogroup RTEMSScoreScheduler
> + * @defgroup RTEMSScoreScheduler Scheduler Handler
> + *
> + * @ingroup RTEMSScore
> + *
> + * @brief This handler encapsulates functionality related to managing sets of
> + *   threads that are ready for execution.
> + *
> + * Schedulers are used by the system to manage sets of threads that are ready
> + * for execution.  A scheduler consists of
> + *
> + * * a scheduler algorithm implementation,
> + *
> + * * a scheduler index and an associated name, and
> + *
> + * * a set of processors own by the scheduler (may be empty, but never overlaps
s/own/owned

> + *   with a set owned by another scheduler).
> + *
> + * Each thread uses exactly one scheduler as its home scheduler.  Threads may
> + * temporarily use also other scheduler due to actions of locking protocols.
s/also other/another

> + *
> + * All properties of a scheduler can be configured and controlled by the user.
> + * Some properties are fixed at link time (defined by application configuration
> + * options), other properties can be changed at runtime through directive
> + * calls.
> + *
> + * The scheduler index, name, and initial processor set are defined for a
> + * particular application by the application configuration.  The schedulers are
> + * registered in the ::_Scheduler_Table which has ::_Scheduler_Count entries.
>   *
>   * @{
>   */
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel