Add missing comments to Flecs headers

Summary: TSIA

Differential Revision: D96177556

Author: SanderMertens

include/flecs.h

@@ -523,6 +523,7 @@ typedef struct ecs_header_t {
     ecs_mixins_t *mixins;       /**< Table with offsets to (optional) mixins */
 } ecs_header_t;
 
+/** Opaque type for table record. */
 typedef struct ecs_table_record_t ecs_table_record_t;
 
 /** @} */
@@ -1398,8 +1399,8 @@ typedef struct ecs_observer_desc_t {
 
     /** Used for internal purposes. Do not set. */
     int32_t *last_event_id;
-    int8_t term_index_;
-    ecs_flags32_t flags_;
+    int8_t term_index_;    /**< Used for internal purposes. Do not set. */
+    ecs_flags32_t flags_;  /**< Used for internal purposes. Do not set. */
 } ecs_observer_desc_t;
 
 /** Used with ecs_emit().
@@ -1537,7 +1538,7 @@ typedef struct ecs_world_info_t {
 
 /** Type that contains information about a query group. */
 typedef struct ecs_query_group_info_t {
-    uint64_t id;
+    uint64_t id;          /**< Group id */
     int32_t match_count;  /**< How often tables have been matched/unmatched */
     int32_t table_count;  /**< Number of tables in group */
     void *ctx;            /**< Group context, returned by on_group_create */
@@ -1581,30 +1582,33 @@ typedef struct EcsDefaultChildComponent {
     ecs_id_t component;  /**< Default component id. */
 } EcsDefaultChildComponent;
 
-/* Non-fragmenting ChildOf relationship. */
+/** Non-fragmenting ChildOf relationship. */
 typedef struct EcsParent {
-    ecs_entity_t value;
+    ecs_entity_t value;     /**< Parent entity */
 } EcsParent;
 
-/* Component with data to instantiate a non-fragmenting tree. */
+/** Component with data to instantiate a non-fragmenting tree. */
 typedef struct {
-    const char *child_name; /* Name of prefab child */
-    ecs_table_t *table;     /* Table in which child will be stored */
-    uint32_t child;         /* Prefab child entity (without generation) */
-    int32_t parent_index;   /* Index into children vector */
+    const char *child_name; /**< Name of prefab child */
+    ecs_table_t *table;     /**< Table in which child will be stored */
+    uint32_t child;         /**< Prefab child entity (without generation) */
+    int32_t parent_index;   /**< Index into children vector */
 } ecs_tree_spawner_child_t;
 
+/** Tree spawner data for a single hierarchy depth. */
 typedef struct {
-    ecs_vec_t children; /* vector<ecs_tree_spawner_child_t> */
+    ecs_vec_t children;     /**< vector<ecs_tree_spawner_child_t> */
 } ecs_tree_spawner_t;
 
+/** Tree instantiation cache component.
+ * Tree instantiation cache, indexed by depth. Tables will have a
+ * (ParentDepth, depth) pair indicating the hierarchy depth. This means that
+ * for different depths, the tables the children are created in will also be
+ * different. Caching tables for different depths therefore speeds up
+ * instantiating trees even when the top level entity is not at the root.
+ */
 typedef struct EcsTreeSpawner {
-    /* Tree instantiation cache, indexed by depth. Tables will have a 
-     * (ParentDepth, depth) pair indicating the hierarchy depth. This means that
-     * for different depths, the tables the children are created in will also be
-     * different. Caching tables for different depths therefore speeds up
-     * instantiating trees even when the top level entity is not at the root. */
-    ecs_tree_spawner_t data[FLECS_TREE_SPAWNER_DEPTH_CACHE_SIZE];
+    ecs_tree_spawner_t data[FLECS_TREE_SPAWNER_DEPTH_CACHE_SIZE]; /**< Cache data indexed by depth */
 } EcsTreeSpawner;
 
 /** @} */
@@ -3371,6 +3375,7 @@ FLECS_ALWAYS_INLINE void* ecs_get_mut_id(
  * @param world The world.
  * @param entity The entity.
  * @param component The component to get/add.
+ * @param size The size of the component.
  * @return The component pointer.
  *
  * @see ecs_emplace_id()
@@ -4128,6 +4133,7 @@ char* ecs_get_path_w_sep(
  * @param sep The separator to use between path elements.
  * @param prefix The initial character to use for root elements.
  * @param buf The buffer to write to.
+ * @param escape Whether to escape separator characters in names.
  *
  * @see ecs_get_path_w_sep()
  */
@@ -5727,6 +5733,7 @@ void* ecs_field_w_size(
  * @param it the iterator.
  * @param size The size of the field type.
  * @param index The index of the field.
+ * @param row The row to get data for.
  * @return A pointer to the data of the field.
  */
 FLECS_API
@@ -6191,6 +6198,8 @@ void ecs_table_swap_rows(
  * @param entity The entity to commit.
  * @param record The entity's record (optional, providing it saves a lookup).
  * @param table The table to commit the entity to.
+ * @param added Components added to the entity.
+ * @param removed Components removed from the entity.
  * @return True if the entity got moved, false otherwise.
  */
 FLECS_API
@@ -6325,7 +6334,21 @@ int32_t ecs_search_relation(
     ecs_id_t *component_out,
     struct ecs_table_record_t **tr_out);
 
-/* Up traversal from entity */
+/** Search for component id by following a relationship, starting from entity.
+ * This operation is the same as ecs_search_relation(), but starts the search
+ * from an entity rather than a table.
+ *
+ * @param world The world.
+ * @param entity The entity from which to begin the search.
+ * @param id The component id to search for.
+ * @param rel The relationship to follow.
+ * @param self If true, also search the entity itself.
+ * @param cr Optional component record for the id.
+ * @param tgt_out Out parameter for the target entity.
+ * @param id_out Out parameter for the found id.
+ * @param tr_out Out parameter for the table record.
+ * @return The index of the id in the entity's type, or -1 if not found.
+ */
 FLECS_API
 int32_t ecs_search_relation_for_entity(
     const ecs_world_t *world,

include/flecs/addons/alerts.h

@@ -28,6 +28,7 @@
 extern "C" {
 #endif
 
+/** Maximum number of severity filters per alert. */
 #define ECS_ALERT_MAX_SEVERITY_FILTERS (4)
 
 /** Module id. */
@@ -56,7 +57,7 @@ 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;
+    ecs_map_t alerts;      /**< Map of active alerts for entity */
 } EcsAlertsActive;
 
 /** Alert severity filter. 
@@ -66,16 +67,16 @@ 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
+    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) */
+    int32_t _var_index;    /**< Index of variable in filter (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 */
     ecs_entity_t entity;

include/flecs/addons/doc.h

@@ -65,7 +65,7 @@ FLECS_API extern const ecs_entity_t EcsDocColor;
  * - EcsDocColor
  */
 typedef struct EcsDocDescription {
-    char *value;
+    char *value;           /**< Description value */
 } EcsDocDescription;
 
 /** Add UUID to entity.