From ba72822993c08f711e4e7e8fadae65c24b93ee44 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Tue, 25 Nov 2025 17:58:19 -0600 Subject: [PATCH] Cleanup: Abstruse documentation comments. Ensure the details on what is and is not de-allocated is described in the documentation comments. Also alphabetize this list. --- level_0/f_abstruse/c/abstruse/abstruse.h | 108 +++++++++++++-------------- level_0/f_abstruse/c/abstruse/map.h | 124 ++++++++++++++++++++++++++----- 2 files changed, 160 insertions(+), 72 deletions(-) diff --git a/level_0/f_abstruse/c/abstruse/abstruse.h b/level_0/f_abstruse/c/abstruse/abstruse.h index 5ded859..a48bb7b 100644 --- a/level_0/f_abstruse/c/abstruse/abstruse.h +++ b/level_0/f_abstruse/c/abstruse/abstruse.h @@ -94,26 +94,26 @@ extern "C" { * Delete the f_abstruse_t structure. * * This only de-allocates the following: - * - a_u8s - * - a_u16s - * - a_u32s - * - a_u64s + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) * - a_i8s * - a_i16s * - a_i32s * - a_i64s - * - a_signeds - * - a_unsigneds - * - a_static (as an f_string_dynamic_t, if size > 0). - * - a_statics (as an f_string_dynamics_t, if size > 0). * - a_map - * - a_maps * - a_map_multi * - a_map_multis + * - a_maps * - a_quantitys * - a_ranges + * - a_signeds * - a_triple * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds * * For all other types, the caller must handle de-allocation to avoid memory leaks. * Provide and use a custom callback if special handling of deallocation is needed. @@ -138,26 +138,26 @@ extern "C" { * Destroy the f_abstruse_t structure. * * This only de-allocates the following: - * - a_u8s - * - a_u16s - * - a_u32s - * - a_u64s + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) * - a_i8s * - a_i16s * - a_i32s * - a_i64s - * - a_signeds - * - a_unsigneds - * - a_static (as an f_string_dynamic_t, if size > 0). - * - a_statics (as an f_string_dynamics_t, if size > 0). * - a_map - * - a_maps * - a_map_multi * - a_map_multis + * - a_maps * - a_quantitys * - a_ranges + * - a_signeds * - a_triple * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds * * For all other types, the caller must handle de-allocation to avoid memory leaks. * Provide and use a custom callback if special handling of deallocation is needed. @@ -182,26 +182,26 @@ extern "C" { * A callback intended to be passed to f_memory_arrays_resize() for an f_abstruses_t structure. * * This callback only de-allocates the following: - * - a_u8s - * - a_u16s - * - a_u32s - * - a_u64s + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) * - a_i8s * - a_i16s * - a_i32s * - a_i64s - * - a_signeds - * - a_unsigneds - * - a_static (as an f_string_dynamic_t, if size > 0). - * - a_statics (as an f_string_dynamics_t, if size > 0). * - a_map - * - a_maps * - a_map_multi * - a_map_multis + * - a_maps * - a_quantitys * - a_ranges + * - a_signeds * - a_triple * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds * * For all other types, the caller must handle de-allocation to avoid memory leaks. * Provide and use a custom callback if special handling of deallocation is needed. @@ -236,26 +236,26 @@ extern "C" { * A callback intended to be passed to f_memory_arrays_adjust() for an f_abstruses_t structure. * * This callback only de-allocates the following: - * - a_u8s - * - a_u16s - * - a_u32s - * - a_u64s + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) * - a_i8s * - a_i16s * - a_i32s * - a_i64s - * - a_signeds - * - a_unsigneds - * - a_static (as an f_string_dynamic_t, if size > 0). - * - a_statics (as an f_string_dynamics_t, if size > 0). * - a_map - * - a_maps * - a_map_multi * - a_map_multis + * - a_maps * - a_quantitys * - a_ranges + * - a_signeds * - a_triple * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds * * For all other types, the caller must handle de-allocation to avoid memory leaks. * Provide and use a custom callback if special handling of deallocation is needed. @@ -290,26 +290,26 @@ extern "C" { * A callback intended to be passed to f_memory_arrays_resize() for an f_abstrusess_t structure. * * This callback only de-allocates the following: - * - a_u8s - * - a_u16s - * - a_u32s - * - a_u64s + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) * - a_i8s * - a_i16s * - a_i32s * - a_i64s - * - a_signeds - * - a_unsigneds - * - a_static (as an f_string_dynamic_t, if size > 0). - * - a_statics (as an f_string_dynamics_t, if size > 0). * - a_map - * - a_maps * - a_map_multi * - a_map_multis + * - a_maps * - a_quantitys * - a_ranges + * - a_signeds * - a_triple * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds * * For all other types, the caller must handle de-allocation to avoid memory leaks. * Provide and use a custom callback if special handling of deallocation is needed. @@ -344,26 +344,26 @@ extern "C" { * A callback intended to be passed to f_memory_arrays_adjust() for an f_abstrusess_t structure. * * This callback only de-allocates the following: - * - a_u8s - * - a_u16s - * - a_u32s - * - a_u64s + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) * - a_i8s * - a_i16s * - a_i32s * - a_i64s - * - a_signeds - * - a_unsigneds - * - a_static (as an f_string_dynamic_t, if size > 0). - * - a_statics (as an f_string_dynamics_t, if size > 0). * - a_map - * - a_maps * - a_map_multi * - a_map_multis + * - a_maps * - a_quantitys * - a_ranges + * - a_signeds * - a_triple * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds * * For all other types, the caller must handle de-allocation to avoid memory leaks. * Provide and use a custom callback if special handling of deallocation is needed. diff --git a/level_0/f_abstruse/c/abstruse/map.h b/level_0/f_abstruse/c/abstruse/map.h index f2d8bf3..af923e2 100644 --- a/level_0/f_abstruse/c/abstruse/map.h +++ b/level_0/f_abstruse/c/abstruse/map.h @@ -86,26 +86,26 @@ extern "C" { * Delete the f_abstruse_map_t structure. * * This only de-allocates the following: - * - a_u8s - * - a_u16s - * - a_u32s - * - a_u64s + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) * - a_i8s * - a_i16s * - a_i32s * - a_i64s - * - a_signeds - * - a_unsigneds - * - a_static (as an f_string_dynamic_t, if size > 0). - * - a_statics (as an f_string_dynamics_t, if size > 0). * - a_map - * - a_maps * - a_map_multi * - a_map_multis + * - a_maps * - a_quantitys * - a_ranges + * - a_signeds * - a_triple * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds * * For all other types, the caller must handle de-allocation to avoid memory leaks. * Provide and use a custom callback if special handling of deallocation is needed. @@ -130,26 +130,26 @@ extern "C" { * Destroy the f_abstruse_map_t structure. * * This only de-allocates the following: - * - a_u8s - * - a_u16s - * - a_u32s - * - a_u64s + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) * - a_i8s * - a_i16s * - a_i32s * - a_i64s - * - a_signeds - * - a_unsigneds - * - a_static (as an f_string_dynamic_t, if size > 0). - * - a_statics (as an f_string_dynamics_t, if size > 0). * - a_map - * - a_maps * - a_map_multi * - a_map_multis + * - a_maps * - a_quantitys * - a_ranges + * - a_signeds * - a_triple * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds * * For all other types, the caller must handle de-allocation to avoid memory leaks. * Provide and use a custom callback if special handling of deallocation is needed. @@ -175,6 +175,28 @@ extern "C" { * * This is only called when shrinking the array and generally should perform deallocations. * + * This callback only de-allocates the following: + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) + * - a_i8s + * - a_i16s + * - a_i32s + * - a_i64s + * - a_map + * - a_map_multi + * - a_map_multis + * - a_maps + * - a_quantitys + * - a_ranges + * - a_signeds + * - a_triple + * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds + * * This does not do parameter checking. * * @param start @@ -204,6 +226,28 @@ extern "C" { * * This is only called when shrinking the array and generally should perform deallocations. * + * This callback only de-allocates the following: + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) + * - a_i8s + * - a_i16s + * - a_i32s + * - a_i64s + * - a_map + * - a_map_multi + * - a_map_multis + * - a_maps + * - a_quantitys + * - a_ranges + * - a_signeds + * - a_triple + * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds + * * This does not do parameter checking. * * @param start @@ -233,6 +277,28 @@ extern "C" { * * This is only called when shrinking the array and generally should perform deallocations. * + * This callback only de-allocates the following: + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) + * - a_i8s + * - a_i16s + * - a_i32s + * - a_i64s + * - a_map + * - a_map_multi + * - a_map_multis + * - a_maps + * - a_quantitys + * - a_ranges + * - a_signeds + * - a_triple + * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds + * * This does not do parameter checking. * * @param start @@ -262,6 +328,28 @@ extern "C" { * * This is only called when shrinking the array and generally should perform deallocations. * + * This callback only de-allocates the following: + * - a_dynamic (if size > 0) + * - a_dynamics (if size > 0) + * - a_i8s + * - a_i16s + * - a_i32s + * - a_i64s + * - a_map + * - a_map_multi + * - a_map_multis + * - a_maps + * - a_quantitys + * - a_ranges + * - a_signeds + * - a_triple + * - a_triples + * - a_u8s + * - a_u16s + * - a_u32s + * - a_u64s + * - a_unsigneds + * * This does not do parameter checking. * * @param start -- 1.8.3.1