diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-08 09:12:39 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-08 09:12:39 +0300 |
commit | da67a19ed9b5e8c5f61926d88653c05ebd3cdf45 (patch) | |
tree | 561f4c4c7083912eab3855dc0c4d5ec2be8c1df8 | |
parent | 2545119112875a098d8d807c84b7f7a3e1bcd338 (diff) |
Cleanup: move public doc-strings into headers for 'makesdna'
Ref T92709
-rw-r--r-- | source/blender/makesdna/DNA_genfile.h | 64 | ||||
-rw-r--r-- | source/blender/makesdna/intern/dna_genfile.c | 57 | ||||
-rw-r--r-- | source/blender/makesdna/intern/dna_utils.c | 32 | ||||
-rw-r--r-- | source/blender/makesdna/intern/dna_utils.h | 17 |
4 files changed, 88 insertions, 82 deletions
diff --git a/source/blender/makesdna/DNA_genfile.h b/source/blender/makesdna/DNA_genfile.h index fda1cbaeae6..5e0cff9fd83 100644 --- a/source/blender/makesdna/DNA_genfile.h +++ b/source/blender/makesdna/DNA_genfile.h @@ -83,6 +83,9 @@ enum eSDNA_StructCompare { SDNA_CMP_UNKNOWN = 3, }; +/** + * Constructs and returns a decoded SDNA structure from the given encoded SDNA data block. + */ struct SDNA *DNA_sdna_from_data(const void *data, const int data_len, bool do_endian_swap, @@ -97,22 +100,58 @@ const struct SDNA *DNA_sdna_current_get(void); void DNA_sdna_current_free(void); struct DNA_ReconstructInfo; +/** + * Pre-process information about how structs in \a newsdna can be reconstructed from structs in + * \a oldsdna. This information is then used to speedup #DNA_struct_reconstruct. + */ struct DNA_ReconstructInfo *DNA_reconstruct_info_create(const struct SDNA *oldsdna, const struct SDNA *newsdna, const char *compare_flags); void DNA_reconstruct_info_free(struct DNA_ReconstructInfo *reconstruct_info); +/** + * Returns the index of the struct info for the struct with the specified name. + */ int DNA_struct_find_nr_ex(const struct SDNA *sdna, const char *str, unsigned int *index_last); int DNA_struct_find_nr(const struct SDNA *sdna, const char *str); +/** + * Does endian swapping on the fields of a struct value. + * + * \param sdna: SDNA of the struct_nr belongs to + * \param struct_nr: Index of struct info within sdna + * \param data: Struct data that is to be converted + */ void DNA_struct_switch_endian(const struct SDNA *sdna, int struct_nr, char *data); +/** + * Constructs and returns an array of byte flags with one element for each struct in oldsdna, + * indicating how it compares to newsdna. + */ const char *DNA_struct_get_compareflags(const struct SDNA *sdna, const struct SDNA *newsdna); +/** + * \param reconstruct_info: Information preprocessed by #DNA_reconstruct_info_create. + * \param old_struct_nr: Index of struct info within oldsdna. + * \param blocks: The number of array elements. + * \param old_blocks: Array of struct data. + * \return An allocated reconstructed struct. + */ void *DNA_struct_reconstruct(const struct DNA_ReconstructInfo *reconstruct_info, int old_struct_nr, int blocks, const void *old_blocks); +/** + * Returns the offset of the field with the specified name and type within the specified + * struct type in #SDNA, -1 on failure. + */ int DNA_elem_offset(struct SDNA *sdna, const char *stype, const char *vartype, const char *name); +/** + * Returns the size of struct fields of the specified type and name. + * + * \param type: Index into sdna->types/types_size + * \param name: Index into sdna->names, + * needed to extract possible pointer/array information. + */ int DNA_elem_size_nr(const struct SDNA *sdna, short type, short name); bool DNA_struct_find(const struct SDNA *sdna, const char *stype); @@ -121,11 +160,22 @@ bool DNA_struct_elem_find(const struct SDNA *sdna, const char *vartype, const char *name); +/** + * Returns the size in bytes of a primitive type. + */ int DNA_elem_type_size(const eSDNA_Type elem_nr); +/** + * Rename a struct + */ bool DNA_sdna_patch_struct(struct SDNA *sdna, const char *struct_name_old, const char *struct_name_new); +/** + * Replace \a elem_old with \a elem_new for struct \a struct_name + * handles search & replace, maintaining surrounding non-identifier characters + * such as pointer & array size. + */ bool DNA_sdna_patch_struct_member(struct SDNA *sdna, const char *struct_name, const char *elem_old, @@ -134,14 +184,28 @@ bool DNA_sdna_patch_struct_member(struct SDNA *sdna, void DNA_sdna_alias_data_ensure(struct SDNA *sdna); /* Alias lookups (using runtime struct member names). */ + +/** + * \note requires #DNA_sdna_alias_data_ensure_structs_map to be called. + */ int DNA_struct_alias_find_nr_ex(const struct SDNA *sdna, const char *str, unsigned int *index_last); +/** + * \note requires #DNA_sdna_alias_data_ensure_structs_map to be called. + */ int DNA_struct_alias_find_nr(const struct SDNA *sdna, const char *str); +/** + * \note requires #DNA_sdna_alias_data_ensure_structs_map to be called. + */ bool DNA_struct_alias_elem_find(const struct SDNA *sdna, const char *stype, const char *vartype, const char *name); +/** + * Separated from #DNA_sdna_alias_data_ensure because it's not needed + * unless we want to lookup aliased struct names (#DNA_struct_alias_find_nr and friends). + */ void DNA_sdna_alias_data_ensure_structs_map(struct SDNA *sdna); #ifdef __cplusplus diff --git a/source/blender/makesdna/intern/dna_genfile.c b/source/blender/makesdna/intern/dna_genfile.c index 8aa2a07d071..bdf29b22787 100644 --- a/source/blender/makesdna/intern/dna_genfile.c +++ b/source/blender/makesdna/intern/dna_genfile.c @@ -177,13 +177,6 @@ static bool ispointer(const char *name) return (name[0] == '*' || (name[0] == '(' && name[1] == '*')); } -/** - * Returns the size of struct fields of the specified type and name. - * - * \param type: Index into sdna->types/types_size - * \param name: Index into sdna->names, - * needed to extract possible pointer/array information. - */ int DNA_elem_size_nr(const SDNA *sdna, short type, short name) { const char *cp = sdna->names[name]; @@ -265,9 +258,6 @@ static int dna_struct_find_nr_ex_impl( return -1; } -/** - * Returns the index of the struct info for the struct with the specified name. - */ int DNA_struct_find_nr_ex(const SDNA *sdna, const char *str, unsigned int *index_last) { return dna_struct_find_nr_ex_impl( @@ -284,7 +274,6 @@ int DNA_struct_find_nr_ex(const SDNA *sdna, const char *str, unsigned int *index index_last); } -/** \note requires #DNA_sdna_alias_data_ensure_structs_map to be called. */ int DNA_struct_alias_find_nr_ex(const SDNA *sdna, const char *str, unsigned int *index_last) { #ifdef WITH_DNA_GHASH @@ -310,7 +299,6 @@ int DNA_struct_find_nr(const SDNA *sdna, const char *str) return DNA_struct_find_nr_ex(sdna, str, &index_last_dummy); } -/** \note requires #DNA_sdna_alias_data_ensure_structs_map to be called. */ int DNA_struct_alias_find_nr(const SDNA *sdna, const char *str) { unsigned int index_last_dummy = UINT_MAX; @@ -544,9 +532,6 @@ static bool init_structDNA(SDNA *sdna, bool do_endian_swap, const char **r_error return true; } -/** - * Constructs and returns a decoded SDNA structure from the given encoded SDNA data block. - */ SDNA *DNA_sdna_from_data(const void *data, const int data_len, bool do_endian_swap, @@ -691,10 +676,6 @@ static void set_compare_flags_for_struct(const SDNA *oldsdna, compare_flags[old_struct_index] = SDNA_CMP_EQUAL; } -/** - * Constructs and returns an array of byte flags with one element for each struct in oldsdna, - * indicating how it compares to newsdna. - */ const char *DNA_struct_get_compareflags(const SDNA *oldsdna, const SDNA *newsdna) { if (oldsdna->structs_len == 0) { @@ -1018,13 +999,6 @@ static int get_member_size_in_bytes(const SDNA *sdna, const SDNA_StructMember *m return type_size * array_length; } -/** - * Does endian swapping on the fields of a struct value. - * - * \param sdna: SDNA of the struct_nr belongs to - * \param struct_nr: Index of struct info within sdna - * \param data: Struct data that is to be converted - */ void DNA_struct_switch_endian(const SDNA *sdna, int struct_nr, char *data) { if (struct_nr == -1) { @@ -1230,13 +1204,6 @@ static void reconstruct_structs(const DNA_ReconstructInfo *reconstruct_info, } } -/** - * \param reconstruct_info: Information preprocessed by #DNA_reconstruct_info_create. - * \param old_struct_nr: Index of struct info within oldsdna. - * \param blocks: The number of array elements. - * \param old_blocks: Array of struct data. - * \return An allocated reconstructed struct. - */ void *DNA_struct_reconstruct(const DNA_ReconstructInfo *reconstruct_info, int old_struct_nr, int blocks, @@ -1534,10 +1501,6 @@ static int compress_reconstruct_steps(ReconstructStep *steps, const int old_step return new_step_count; } -/** - * Pre-process information about how structs in \a newsdna can be reconstructed from structs in - * \a oldsdna. This information is then used to speedup #DNA_struct_reconstruct. - */ DNA_ReconstructInfo *DNA_reconstruct_info_create(const SDNA *oldsdna, const SDNA *newsdna, const char *compare_flags) @@ -1597,10 +1560,6 @@ void DNA_reconstruct_info_free(DNA_ReconstructInfo *reconstruct_info) MEM_freeN(reconstruct_info); } -/** - * Returns the offset of the field with the specified name and type within the specified - * struct type in #SDNA, -1 on failure. - */ int DNA_elem_offset(SDNA *sdna, const char *stype, const char *vartype, const char *name) { const int SDNAnr = DNA_struct_find_nr(sdna, stype); @@ -1632,7 +1591,6 @@ bool DNA_struct_elem_find(const SDNA *sdna, return false; } -/** \note requires #DNA_sdna_alias_data_ensure_structs_map to be called. */ bool DNA_struct_alias_elem_find(const SDNA *sdna, const char *stype, const char *vartype, @@ -1651,9 +1609,6 @@ bool DNA_struct_alias_elem_find(const SDNA *sdna, return false; } -/** - * Returns the size in bytes of a primitive type. - */ int DNA_elem_type_size(const eSDNA_Type elem_nr) { /* should contain all enum types */ @@ -1696,9 +1651,6 @@ static bool DNA_sdna_patch_struct_nr(SDNA *sdna, sdna->types[struct_info->type] = struct_name_new; return true; } -/** - * Rename a struct - */ bool DNA_sdna_patch_struct(SDNA *sdna, const char *struct_name_old, const char *struct_name_new) { const int struct_name_old_nr = DNA_struct_find_nr(sdna, struct_name_old); @@ -1756,11 +1708,6 @@ static bool DNA_sdna_patch_struct_member_nr(SDNA *sdna, } return false; } -/** - * Replace \a elem_old with \a elem_new for struct \a struct_name - * handles search & replace, maintaining surrounding non-identifier characters - * such as pointer & array size. - */ bool DNA_sdna_patch_struct_member(SDNA *sdna, const char *struct_name, const char *elem_old, @@ -1909,10 +1856,6 @@ void DNA_sdna_alias_data_ensure(SDNA *sdna) BLI_ghash_free(elem_map_alias_from_static, MEM_freeN, NULL); } -/** - * Separated from #DNA_sdna_alias_data_ensure because it's not needed - * unless we want to lookup aliased struct names (#DNA_struct_alias_find_nr and friends). - */ void DNA_sdna_alias_data_ensure_structs_map(SDNA *sdna) { DNA_sdna_alias_data_ensure(sdna); diff --git a/source/blender/makesdna/intern/dna_utils.c b/source/blender/makesdna/intern/dna_utils.c index f050934b5b3..b2e2e263ea3 100644 --- a/source/blender/makesdna/intern/dna_utils.c +++ b/source/blender/makesdna/intern/dna_utils.c @@ -39,10 +39,6 @@ /** \name Struct Member Evaluation * \{ */ -/** - * Parses the `[n1][n2]...` on the end of an array name - * and returns the number of array elements `n1 * n2 ...`. - */ int DNA_elem_array_size(const char *str) { int result = 1; @@ -106,9 +102,6 @@ uint DNA_elem_id_offset_end(const char *elem_full) return elem_full_offset; } -/** - * \a elem_dst must be at least the size of \a elem_src. - */ uint DNA_elem_id_strip_copy(char *elem_dst, const char *elem_src) { const uint elem_src_offset = DNA_elem_id_offset_start(elem_src); @@ -129,10 +122,6 @@ uint DNA_elem_id_strip(char *elem) return elem_trim_len; } -/** - * Check if 'var' matches '*var[3]' for eg, - * return true if it does, with start/end offsets. - */ bool DNA_elem_id_match(const char *elem_search, const int elem_search_len, const char *elem_full, @@ -151,9 +140,6 @@ bool DNA_elem_id_match(const char *elem_search, return false; } -/** - * Return a renamed dna name, allocated from \a mem_arena. - */ char *DNA_elem_id_rename(struct MemArena *mem_arena, const char *elem_src, const int elem_src_len, @@ -297,19 +283,15 @@ void DNA_alias_maps(enum eDNA_RenameDir version_dir, GHash **r_struct_map, GHash /** \name Struct Name Legacy Hack * \{ */ -/** - * DNA Compatibility Hack - * ====================== - * - * Only keep this for compatibility: **NEVER ADD NEW STRINGS HERE**. - * - * The renaming here isn't complete, references to the old struct names - * are still included in DNA, now fixing these struct names properly - * breaks forward compatibility. Leave these as-is, but don't add to them! - * See D4342#98780 - */ const char *DNA_struct_rename_legacy_hack_static_from_alias(const char *name) { + /* Only keep this for compatibility: *NEVER ADD NEW STRINGS HERE*. + * + * The renaming here isn't complete, references to the old struct names + * are still included in DNA, now fixing these struct names properly + * breaks forward compatibility. Leave these as-is, but don't add to them! + * See D4342#98780. */ + /* 'bScreen' replaces the old IrisGL 'Screen' struct */ if (STREQ("bScreen", name)) { return "Screen"; diff --git a/source/blender/makesdna/intern/dna_utils.h b/source/blender/makesdna/intern/dna_utils.h index f711056c575..b89c45a7a43 100644 --- a/source/blender/makesdna/intern/dna_utils.h +++ b/source/blender/makesdna/intern/dna_utils.h @@ -27,16 +27,30 @@ extern "C" { struct GHash; struct MemArena; +/** + * Parses the `[n1][n2]...` on the end of an array name + * and returns the number of array elements `n1 * n2 ...`. + */ int DNA_elem_array_size(const char *str); uint DNA_elem_id_offset_start(const char *elem_full); uint DNA_elem_id_offset_end(const char *elem_full); +/** + * \a elem_dst must be at least the size of \a elem_src. + */ uint DNA_elem_id_strip_copy(char *elem_dst, const char *elem_src); uint DNA_elem_id_strip(char *elem); +/** + * Check if 'var' matches '*var[3]' for eg, + * return true if it does, with start/end offsets. + */ bool DNA_elem_id_match(const char *elem_search, const int elem_search_len, const char *elem_full, uint *r_elem_full_offset); +/** + * Return a renamed dna name, allocated from \a mem_arena. + */ char *DNA_elem_id_rename(struct MemArena *mem_arena, const char *elem_src, const int elem_src_len, @@ -56,6 +70,9 @@ void DNA_alias_maps(enum eDNA_RenameDir version_dir, struct GHash **r_elem_map); const char *DNA_struct_rename_legacy_hack_alias_from_static(const char *name); +/** + * DNA Compatibility Hack. + */ const char *DNA_struct_rename_legacy_hack_static_from_alias(const char *name); #ifdef __cplusplus |