Skip to content

Commit 5e7ec48

Browse files
SanderMertensSanderMertens
committed
Document API support functions
1 parent e09185e commit 5e7ec48

File tree

4 files changed

+176
-38
lines changed

4 files changed

+176
-38
lines changed

‎distr/flecs.c‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -33665,6 +33665,13 @@ int flecs_term_ref_finalize_flags(
3366533665
return 0;
3366633666
}
3366733667

33668+
static
33669+
bool flecs_identifier_is_0(
33670+
const char *id)
33671+
{
33672+
return id[0] == '#' && id[1] == '0' && !id[2];
33673+
}
33674+
3366833675
static
3366933676
int flecs_term_ref_lookup(
3367033677
const ecs_world_t *world,
@@ -34593,12 +34600,6 @@ int flecs_term_finalize(
3459334600
return 0;
3459434601
}
3459534602

34596-
bool flecs_identifier_is_0(
34597-
const char *id)
34598-
{
34599-
return id[0] == '#' && id[1] == '0' && !id[2];
34600-
}
34601-
3460234603
bool ecs_term_ref_is_set(
3460334604
const ecs_term_ref_t *ref)
3460434605
{

‎distr/flecs.h‎

Lines changed: 81 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3915,27 +3915,45 @@ extern "C" {
39153915
/** Maximum length of a parser token (used by parser-related addons) */
39163916
#define ECS_MAX_TOKEN_SIZE (256)
39173917

3918+
/** Convert a C module name into a path.
3919+
* This operation converts a PascalCase name to a path, for example MyFooModule
3920+
* into my.foo.module.
3921+
*
3922+
* @param c_name The C module name
3923+
* @return The path.
3924+
*/
39183925
FLECS_API
39193926
char* flecs_module_path_from_c(
39203927
const char *c_name);
39213928

3922-
bool flecs_identifier_is_0(
3923-
const char *id);
3924-
3925-
/* Constructor that zeromem's a component value */
3929+
/** Constructor that zeromem's a component value.
3930+
*
3931+
* @param ptr Pointer to the value.
3932+
* @param count Number of elements to construct.
3933+
* @param type_info Type info for the component.
3934+
*/
39263935
FLECS_API
39273936
void flecs_default_ctor(
39283937
void *ptr,
39293938
int32_t count,
3930-
const ecs_type_info_t *ctx);
3939+
const ecs_type_info_t *type_info);
39313940

3932-
/* Create allocated string from format */
3941+
/** Create allocated string from format.
3942+
*
3943+
* @param fmt The format string.
3944+
* @param args Format arguments.
3945+
* @return The formatted string.
3946+
*/
39333947
FLECS_DBG_API
39343948
char* flecs_vasprintf(
39353949
const char *fmt,
39363950
va_list args);
39373951

3938-
/* Create allocated string from format */
3952+
/** Create allocated string from format.
3953+
*
3954+
* @param fmt The format string.
3955+
* @return The formatted string.
3956+
*/
39393957
FLECS_API
39403958
char* flecs_asprintf(
39413959
const char *fmt,
@@ -4062,51 +4080,101 @@ void flecs_resume_readonly(
40624080
ecs_world_t *world,
40634081
ecs_suspend_readonly_state_t *state);
40644082

4083+
/** Number of observed entities in table.
4084+
* Operation is public to support test cases.
4085+
*
4086+
* @param table The table.
4087+
*/
40654088
FLECS_DBG_API
40664089
int32_t flecs_table_observed_count(
40674090
const ecs_table_t *table);
40684091

4092+
/** Print backtrace to specified stream.
4093+
*
4094+
* @param stream The stream to use for printing the backtrace.
4095+
*/
40694096
FLECS_DBG_API
40704097
void flecs_dump_backtrace(
40714098
void *stream);
40724099

4100+
/** Increase refcount of poly object.
4101+
*
4102+
* @param poly The poly object.
4103+
* @return The refcount after incrementing.
4104+
*/
40734105
FLECS_API
40744106
int32_t flecs_poly_claim_(
40754107
ecs_poly_t *poly);
40764108

4109+
/** Decrease refcount of poly object.
4110+
*
4111+
* @param poly The poly object.
4112+
* @return The refcount after decrementing.
4113+
*/
40774114
FLECS_API
40784115
int32_t flecs_poly_release_(
40794116
ecs_poly_t *poly);
40804117

4118+
#define flecs_poly_claim(poly) \
4119+
flecs_poly_claim_(ECS_CONST_CAST(void*, reinterpret_cast<const void*>(poly)))
4120+
4121+
#define flecs_poly_release(poly) \
4122+
flecs_poly_release_(ECS_CONST_CAST(void*, reinterpret_cast<const void*>(poly)))
4123+
4124+
/** Return refcount of poly object.
4125+
*
4126+
* @param poly The poly object.
4127+
* @return Refcount of the poly object.
4128+
*/
40814129
FLECS_API
40824130
int32_t flecs_poly_refcount(
40834131
ecs_poly_t *poly);
40844132

4133+
/** Get unused index for static world local component id array.
4134+
* This operation returns an unused index for the world-local component id
4135+
* array. This index can be used by language bindings to obtain a component id.
4136+
*
4137+
* @return Unused index for component id array.
4138+
*/
40854139
FLECS_API
40864140
int32_t flecs_component_ids_index_get(void);
40874141

4142+
/** Get world local component id.
4143+
*
4144+
* @param world The world.
4145+
* @param index Component id array index.
4146+
* @return The component id.
4147+
*/
40884148
FLECS_API
40894149
ecs_entity_t flecs_component_ids_get(
40904150
const ecs_world_t *world,
40914151
int32_t index);
40924152

4153+
/** Get alive world local component id.
4154+
* Same as flecs_component_ids_get, but return 0 if component is no longer
4155+
* alive.
4156+
*
4157+
* @param world The world.
4158+
* @param index Component id array index.
4159+
* @return The component id.
4160+
*/
40934161
FLECS_API
40944162
ecs_entity_t flecs_component_ids_get_alive(
40954163
const ecs_world_t *stage_world,
40964164
int32_t index);
40974165

4166+
/** Set world local component id.
4167+
*
4168+
* @param world The world.
4169+
* @param index Component id array index.
4170+
* @param id The component id.
4171+
*/
40984172
FLECS_API
40994173
void flecs_component_ids_set(
41004174
ecs_world_t *world,
41014175
int32_t index,
41024176
ecs_entity_t id);
41034177

4104-
#define flecs_poly_claim(poly) \
4105-
flecs_poly_claim_(ECS_CONST_CAST(void*, reinterpret_cast<const void*>(poly)))
4106-
4107-
#define flecs_poly_release(poly) \
4108-
flecs_poly_release_(ECS_CONST_CAST(void*, reinterpret_cast<const void*>(poly)))
4109-
41104178

41114179
/** Calculate offset from address */
41124180
#ifdef __cplusplus

‎include/flecs/private/api_support.h‎

Lines changed: 81 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -28,27 +28,45 @@ extern "C" {
2828
/** Maximum length of a parser token (used by parser-related addons) */
2929
#define ECS_MAX_TOKEN_SIZE (256)
3030

31+
/** Convert a C module name into a path.
32+
* This operation converts a PascalCase name to a path, for example MyFooModule
33+
* into my.foo.module.
34+
*
35+
* @param c_name The C module name
36+
* @return The path.
37+
*/
3138
FLECS_API
3239
char* flecs_module_path_from_c(
3340
const char *c_name);
3441

35-
bool flecs_identifier_is_0(
36-
const char *id);
37-
38-
/* Constructor that zeromem's a component value */
42+
/** Constructor that zeromem's a component value.
43+
*
44+
* @param ptr Pointer to the value.
45+
* @param count Number of elements to construct.
46+
* @param type_info Type info for the component.
47+
*/
3948
FLECS_API
4049
void flecs_default_ctor(
4150
void *ptr,
4251
int32_t count,
43-
const ecs_type_info_t *ctx);
52+
const ecs_type_info_t *type_info);
4453

45-
/* Create allocated string from format */
54+
/** Create allocated string from format.
55+
*
56+
* @param fmt The format string.
57+
* @param args Format arguments.
58+
* @return The formatted string.
59+
*/
4660
FLECS_DBG_API
4761
char* flecs_vasprintf(
4862
const char *fmt,
4963
va_list args);
5064

51-
/* Create allocated string from format */
65+
/** Create allocated string from format.
66+
*
67+
* @param fmt The format string.
68+
* @return The formatted string.
69+
*/
5270
FLECS_API
5371
char* flecs_asprintf(
5472
const char *fmt,
@@ -175,51 +193,101 @@ void flecs_resume_readonly(
175193
ecs_world_t *world,
176194
ecs_suspend_readonly_state_t *state);
177195

196+
/** Number of observed entities in table.
197+
* Operation is public to support test cases.
198+
*
199+
* @param table The table.
200+
*/
178201
FLECS_DBG_API
179202
int32_t flecs_table_observed_count(
180203
const ecs_table_t *table);
181204

205+
/** Print backtrace to specified stream.
206+
*
207+
* @param stream The stream to use for printing the backtrace.
208+
*/
182209
FLECS_DBG_API
183210
void flecs_dump_backtrace(
184211
void *stream);
185212

213+
/** Increase refcount of poly object.
214+
*
215+
* @param poly The poly object.
216+
* @return The refcount after incrementing.
217+
*/
186218
FLECS_API
187219
int32_t flecs_poly_claim_(
188220
ecs_poly_t *poly);
189221

222+
/** Decrease refcount of poly object.
223+
*
224+
* @param poly The poly object.
225+
* @return The refcount after decrementing.
226+
*/
190227
FLECS_API
191228
int32_t flecs_poly_release_(
192229
ecs_poly_t *poly);
193230

231+
#define flecs_poly_claim(poly) \
232+
flecs_poly_claim_(ECS_CONST_CAST(void*, reinterpret_cast<const void*>(poly)))
233+
234+
#define flecs_poly_release(poly) \
235+
flecs_poly_release_(ECS_CONST_CAST(void*, reinterpret_cast<const void*>(poly)))
236+
237+
/** Return refcount of poly object.
238+
*
239+
* @param poly The poly object.
240+
* @return Refcount of the poly object.
241+
*/
194242
FLECS_API
195243
int32_t flecs_poly_refcount(
196244
ecs_poly_t *poly);
197245

246+
/** Get unused index for static world local component id array.
247+
* This operation returns an unused index for the world-local component id
248+
* array. This index can be used by language bindings to obtain a component id.
249+
*
250+
* @return Unused index for component id array.
251+
*/
198252
FLECS_API
199253
int32_t flecs_component_ids_index_get(void);
200254

255+
/** Get world local component id.
256+
*
257+
* @param world The world.
258+
* @param index Component id array index.
259+
* @return The component id.
260+
*/
201261
FLECS_API
202262
ecs_entity_t flecs_component_ids_get(
203263
const ecs_world_t *world,
204264
int32_t index);
205265

266+
/** Get alive world local component id.
267+
* Same as flecs_component_ids_get, but return 0 if component is no longer
268+
* alive.
269+
*
270+
* @param world The world.
271+
* @param index Component id array index.
272+
* @return The component id.
273+
*/
206274
FLECS_API
207275
ecs_entity_t flecs_component_ids_get_alive(
208276
const ecs_world_t *stage_world,
209277
int32_t index);
210278

279+
/** Set world local component id.
280+
*
281+
* @param world The world.
282+
* @param index Component id array index.
283+
* @param id The component id.
284+
*/
211285
FLECS_API
212286
void flecs_component_ids_set(
213287
ecs_world_t *world,
214288
int32_t index,
215289
ecs_entity_t id);
216290

217-
#define flecs_poly_claim(poly) \
218-
flecs_poly_claim_(ECS_CONST_CAST(void*, reinterpret_cast<const void*>(poly)))
219-
220-
#define flecs_poly_release(poly) \
221-
flecs_poly_release_(ECS_CONST_CAST(void*, reinterpret_cast<const void*>(poly)))
222-
223291

224292
/** Calculate offset from address */
225293
#ifdef __cplusplus

‎src/query/validator.c‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,13 @@ int flecs_term_ref_finalize_flags(
112112
return 0;
113113
}
114114

115+
static
116+
bool flecs_identifier_is_0(
117+
const char *id)
118+
{
119+
return id[0] == '#' && id[1] == '0' && !id[2];
120+
}
121+
115122
static
116123
int flecs_term_ref_lookup(
117124
const ecs_world_t *world,
@@ -1040,12 +1047,6 @@ int flecs_term_finalize(
10401047
return 0;
10411048
}
10421049

1043-
bool flecs_identifier_is_0(
1044-
const char *id)
1045-
{
1046-
return id[0] == '#' && id[1] == '0' && !id[2];
1047-
}
1048-
10491050
bool ecs_term_ref_is_set(
10501051
const ecs_term_ref_t *ref)
10511052
{

0 commit comments

Comments
 (0)