Cleanup: move public doc-strings into headers for 'makesdna'
Ref T92709
This commit is contained in:
parent
2545119112
commit
da67a19ed9
Notes:
blender-bot
2023-02-13 17:15:14 +01:00
Referenced by issue #93854, Relocate doc-strings into public headers Referenced by issue #92709, Code Style: documentation at declaration or definition
|
@ -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
|
||||
|
|
|
@ -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);
|
||||
|
|
|
@ -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";
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue