Add missing comments to Flecs headers (#2010)

Summary:
Pull Request resolved: #2010

TSIA

Differential Revision: D96177556

Author: SanderMertens

include/flecs.h

@@ -28,35 +28,36 @@
 extern "C" {
 #endif
 
+/** Maximum number of severity filters per alert. */
 #define ECS_ALERT_MAX_SEVERITY_FILTERS (4)
 
-/** Module id. */
+/** Module ID. */
 FLECS_API extern ECS_COMPONENT_DECLARE(FlecsAlerts);
 
-/* Module components */
+/** Module components. */
 
-FLECS_API extern ECS_COMPONENT_DECLARE(EcsAlert);          /**< Component added to alert, and used as first element of alert severity pair. */
+FLECS_API extern ECS_COMPONENT_DECLARE(EcsAlert);          /**< Component added to alert, and used as the first element of the alert severity pair. */
 FLECS_API extern ECS_COMPONENT_DECLARE(EcsAlertInstance);  /**< Component added to alert instance. */
-FLECS_API extern ECS_COMPONENT_DECLARE(EcsAlertsActive);   /**< Component added to alert source which tracks how many active alerts there are. */
-FLECS_API extern ECS_COMPONENT_DECLARE(EcsAlertTimeout);   /**< Component added to alert which tracks how long an alert has been inactive. */
+FLECS_API extern ECS_COMPONENT_DECLARE(EcsAlertsActive);   /**< Component added to alert source, which tracks how many active alerts there are. */
+FLECS_API extern ECS_COMPONENT_DECLARE(EcsAlertTimeout);   /**< Component added to alert, which tracks how long an alert has been inactive. */
 
-/* Alert severity tags */
+/** Alert severity tags. */
 FLECS_API extern ECS_TAG_DECLARE(EcsAlertInfo);            /**< Info alert severity. */
 FLECS_API extern ECS_TAG_DECLARE(EcsAlertWarning);         /**< Warning alert severity. */
 FLECS_API extern ECS_TAG_DECLARE(EcsAlertError);           /**< Error alert severity. */
 FLECS_API extern ECS_TAG_DECLARE(EcsAlertCritical);        /**< Critical alert severity. */
 
 /** Component added to alert instance. */
 typedef struct EcsAlertInstance {
-    char *message; /**< Generated alert message */
+    char *message; /**< Generated alert message. */
 } EcsAlertInstance;
 
 /** Map with active alerts for entity. */
 typedef struct EcsAlertsActive {
-    int32_t info_count;    /**< Number of alerts for source with info severity */
-    int32_t warning_count; /**< Number of alerts for source with warning severity */
-    int32_t error_count;   /**< Number of alerts for source with error severity */
-    ecs_map_t alerts;
+    int32_t info_count;    /**< Number of alerts for source with info severity. */
+    int32_t warning_count; /**< Number of alerts for source with warning severity. */
+    int32_t error_count;   /**< Number of alerts for source with error severity. */
+    ecs_map_t alerts;      /**< Map of active alerts for entity. */
 } EcsAlertsActive;
 
 /** Alert severity filter. 
@@ -66,18 +67,18 @@ typedef struct EcsAlertsActive {
  * severity of an alert from Warning to Error.
  */
 typedef struct ecs_alert_severity_filter_t {
-    ecs_entity_t severity; /* Severity kind */
-    ecs_id_t with;         /* Component to match */
-    const char *var;       /* Variable to match component on. Do not include the
-                            * '$' character. Leave to NULL for $this. */
-    int32_t _var_index;    /* Index of variable in filter (do not set) */
+    ecs_entity_t severity; /**< Severity kind. */
+    ecs_id_t with;         /**< Component to match. */
+    const char *var;       /**< Variable to match component on. Do not include the
+                            * '$' character. Leave as NULL for $this. */
+    int32_t _var_index;    /**< Index of variable in query (do not set). */
 } ecs_alert_severity_filter_t;
 
 /** Alert descriptor, used with ecs_alert_init(). */
 typedef struct ecs_alert_desc_t {
-    int32_t _canary;
+    int32_t _canary;       /**< Used for validity testing. Do not set. */
 
-    /** Entity associated with alert */
+    /** Entity associated with alert. */
     ecs_entity_t entity;
 
     /** Alert query. An alert will be created for each entity that matches the
@@ -96,13 +97,13 @@ typedef struct ecs_alert_desc_t {
      */
     const char *message;
 
-    /** User friendly name. Will only be set if FLECS_DOC addon is enabled. */
+    /** User-friendly name. Will only be set if FLECS_DOC addon is enabled. */
     const char *doc_name;
 
-    /** Description of alert. Will only be set if FLECS_DOC addon is enabled */
+    /** Description of alert. Will only be set if FLECS_DOC addon is enabled. */
     const char *brief;
 
-    /** Metric kind. Must be EcsAlertInfo, EcsAlertWarning, EcsAlertError or
+    /** Alert severity. Must be EcsAlertInfo, EcsAlertWarning, EcsAlertError, or
      * EcsAlertCritical. Defaults to EcsAlertError. */
     ecs_entity_t severity;
 
@@ -114,20 +115,20 @@ typedef struct ecs_alert_desc_t {
 
     /** The retain period specifies how long an alert must be inactive before it
      * is cleared. This makes it easier to track noisy alerts. While an alert is
-     * inactive its duration won't increase.
+     * inactive, its duration won't increase.
      * When the retain period is 0, the alert will clear immediately after it no
      * longer matches the alert query. */
     ecs_ftime_t retain_period;
 
-    /** Alert when member value is out of range. Uses the warning/error ranges
+    /** Alert when member value is out of range. Uses the warning and error ranges
      * assigned to the member in the MemberRanges component (optional). */
     ecs_entity_t member;
 
-    /** (Component) id of member to monitor. If left to 0 this will be set to
+    /** (Component) ID of member to monitor. If left to 0, this will be set to
      * the parent entity of the member (optional). */
     ecs_id_t id;
 
-    /** Variable from which to fetch the member (optional). When left to NULL
+    /** Variable from which to fetch the member (optional). When left to NULL,
      * 'id' will be obtained from $this. */
     const char *var;
 } ecs_alert_desc_t;

include/flecs/addons/alerts.h

@@ -5,7 +5,7 @@
  * The app addon is a wrapper around the application's main loop. Its main
  * purpose is to provide a hook to modules that need to take control of the
  * main loop, as is for example the case with native applications that use
- * emscripten with webGL.
+ * Emscripten with WebGL.
  */
 
 #ifdef FLECS_APP
@@ -36,17 +36,17 @@ typedef int(*ecs_app_init_action_t)(
 /** Used with ecs_app_run(). */
 typedef struct ecs_app_desc_t {
     ecs_ftime_t target_fps;   /**< Target FPS. */
-    ecs_ftime_t delta_time;   /**< Frame time increment (0 for measured values) */
+    ecs_ftime_t delta_time;   /**< Frame time increment (0 for measured values). */
     int32_t threads;          /**< Number of threads. */
-    int32_t frames;           /**< Number of frames to run (0 for infinite) */
-    bool enable_rest;         /**< Enables ECS access over HTTP, necessary for explorer */
-    bool enable_stats;      /**< Periodically collect statistics */
-    uint16_t port;            /**< HTTP port used by REST API */
+    int32_t frames;           /**< Number of frames to run (0 for infinite). */
+    bool enable_rest;         /**< Enables ECS access over HTTP, necessary for the explorer. */
+    bool enable_stats;      /**< Periodically collects statistics. */
+    uint16_t port;            /**< HTTP port used by REST API. */
 
-    ecs_app_init_action_t init; /**< If set, function is ran before starting the
+    ecs_app_init_action_t init; /**< If set, the function is run before starting the
                                  * main loop. */
 
-    void *ctx;                /**< Reserved for custom run/frame actions */
+    void *ctx;                /**< Reserved for custom run and frame actions. */
 } ecs_app_desc_t;
 
 /** Callback type for run action. */
@@ -61,27 +61,28 @@ typedef int(*ecs_app_frame_action_t)(
 
 /** Run application.
  * This will run the application with the parameters specified in desc. After
- * the application quits (ecs_quit() is called) the world will be cleaned up.
+ * the application quits (ecs_quit() is called), the world will be cleaned up.
  *
  * If a custom run action is set, it will be invoked by this operation. The
  * default run action calls the frame action in a loop until it returns a
  * non-zero value.
  *
  * @param world The world.
  * @param desc Application parameters.
+ * @return Zero if success, non-zero if failed.
  */
 FLECS_API
 int ecs_app_run(
     ecs_world_t *world,
     ecs_app_desc_t *desc);
 
 /** Default frame callback.
- * This operation will run a single frame. By default this operation will invoke
+ * This operation will run a single frame. By default, this operation will invoke
  * ecs_progress() directly, unless a custom frame action is set.
  *
  * @param world The world.
  * @param desc The desc struct passed to ecs_app_run().
- * @return value returned by ecs_progress()
+ * @return Value returned by ecs_progress().
  */
 FLECS_API
 int ecs_app_run_frame(
@@ -92,6 +93,7 @@ int ecs_app_run_frame(
  * See ecs_app_run().
  *
  * @param callback The run action.
+ * @return Zero if success, non-zero if failed.
  */
 FLECS_API
 int ecs_app_set_run_action(
@@ -101,6 +103,7 @@ int ecs_app_set_run_action(
  * See ecs_app_run_frame().
  *
  * @param callback The frame action.
+ * @return Zero if success, non-zero if failed.
  */
 FLECS_API
 int ecs_app_set_frame_action(