Page MenuHome

Proposal: BKE_library and BKE_main API naming: prefixes conventions
Confirmed, LowPublicDESIGN

Description

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.


Current situation

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-onlyBKE_libblock_Those are ID-generic functions
data-block levelBKE_id_Those take into account the type of data-blocks
Main levelBKE_main_id_Those potentially affect all data-blocks in given bmain
Library data-blocksBKE_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 remappingBKE_libblock_Those are ID-generic functions
CallbacksBKE_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 reaflie.c for in undo code currently
BKE_library_override.h (library overrides)On a single IDBKE_override_library_
On the whole MainBKE_main_override_library_

Remarks

  • 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?

Proposal

First, rename BKE_library_idmap.h to BKE_main_idmap.h (and same for the .c implementation of course).

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_library.h (ID management)low-level ID-onlyBKE_libblock_->BKE_lib_libblock_
data-block levelBKE_id_->BKE_lib_id_
Main levelBKE_main_id_->BKE_lib_main_
Library data-blocksBKE_library_->BKE_lib_library_
BKE_library_query.h (queries over Main database)BKE_library_->BKE_lib_query_
BKE_library_remap.h (remapping of IDs)Actual remappingBKE_libblock_->BKE_lib_remap_libblock_
CallbacksBKE_library_callback_->BKE_lib_remap_callback_
BKE_library_override.h (library overrides)On a single IDBKE_override_library_->BKE_lib_override_library_
On the whole MainBKE_main_override_library_->BKE_lib_override_library_main_

This should be enforced for all new functions added there, as well as any future cleanup/renaming.

Related Objects

Event Timeline

Bastien Montagne (mont29) triaged this task as Low priority.Dec 20 2019, 4:04 PM
Bastien Montagne (mont29) created this task.

Note that this is an initial draft, am not happy with all proposed new names,. E.g. the override case is a bit hairy, since we end up using library for two different meaning (lib, as 'par of ID management code`, and in library override, i.e. 'override of linked data-blocks' [opposed to 'dynamic override']), none of them being fully related to actual Library data-block itself…