The purpose of this task is not to actually rename all our functions in those headers right now. But rather to define (and document, in a comment in those headers) proper rules for the BKE_xxx prefixes we should use for these 'public' APIs.
In the past years, me and the few other devs that had to work in that area tried to sanitize a bit old names, but looking at current code state I have the feeling this was at best a mixed success so far.
Besides old, never-yet-renamed functions, currently we seem to motsly follow those rules for new/renamed functions:
|BKE_main.h (affecting Main structure itself)||BKE_main_|
|BKE_library.h (ID management)||low-level ID-only||BKE_libblock_||Those are ID-generic functions|
|data-block level||BKE_id_||Those take into account the type of data-blocks|
|Main level||BKE_main_id_||Those potentially affect all data-blocks in given bmain|
|Library data-blocks||BKE_library_||Those are specific to Library data-blocks|
|BKE_library_query.h (queries over Main database)||BKE_library_|
|BKE_library_remap.h (remapping of IDs)||Actual remapping||BKE_libblock_||Those are ID-generic functions|
|Callbacks||BKE_library_callback_||For ID users outside of Main area|
|BKE_library_idmap.h (mapping from ID type/name to id)||BKE_main_idmap_||Only used in reafile.c for in undo code currently|
|BKE_library_override.h (library overrides)||On a single ID||BKE_override_library_|
|On the whole Main||BKE_main_override_library_|
- BKE_library_idmap.h should really be name BKE_main_idmap.h, this is not really related to ID management (though it could be useful there in some cases), this is just an alternative 'view' of given Main content.
- library is a confusing term, since it is used for both a specific datablock type, and as the generic ID management word.
- libblock (when only considering the actual generic ID part of a data-block) versus id (when considering the whole data-block, including its type-specific stuff) is rather confusing and somewhat misleading. Also because we do not use libblock wording anywhere else in Blender codebase afaik. Not sure we’d benefit much about changing that now though, given how deep those functions go allover Blender codebase?
First, rename BKE_library_idmap.h to BKE_main_idmap.h (and same for the .c implementation of course).
Then rename BKE_library files to use BKE_lib prefix instead (changing BKE_library.h to BKE_lib_id.h to avoid having too common/collision-risky name).
Finally split out Library data-blocks-specific functions into their own BKE_library file.
Then document this convention in respective headers, based on following principles:
- File naming scope:
- BKE_main files are for operations over the Main database itself, or generating extra temp data to help working with it. Those should typically not affect the data-blocks themselves.
- BKE_library files are for operations over data-blocks themselves, although they might alter Main as well (when creating/Renaming/deleting an ID e.g.).
- Use a common small prefix referring to a same header file:
- BKE_main_ is kind of obvious.
- BKE_lib_ for all the BKE_library files, to keep it short, and distinguish it from actual Library data-block specific code.
|BKE_main.h (affecting Main structure itself)||BKE_main_||->||BKE_main_|
|BKE_main_idmap.h (mapping from ID type/name to id)||BKE_main_idmap_||->||BKE_main_idmap_|
|BKE_lib_id.h (ID management)||low-level ID-only||BKE_libblock_||->||BKE_lib_libblock_|
|BKE_lib_query.h (queries over Main database)||BKE_library_||->||BKE_lib_query_|
|BKE_lib_remap.h (remapping of IDs)||Actual remapping||BKE_libblock_||->||BKE_lib_remap_libblock_|
|BKE_lib_override.h (library overrides)||On a single ID||BKE_override_library_||->||BKE_lib_override_library_|
|On the whole Main||BKE_main_override_library_||->||BKE_lib_override_library_main_|
|BKE_library.h (Library IDs)||Library data-blocks||BKE_library_||->||BKE_library_|
This should be enforced for all new functions added there, as well as any future cleanup/renaming.