diff options
author | Bastien Montagne <b.mont29@gmail.com> | 2020-02-10 17:05:54 +0300 |
---|---|---|
committer | Bastien Montagne <b.mont29@gmail.com> | 2020-02-10 17:05:54 +0300 |
commit | cd48b132ffafc80347a668b3c1cf295abf399f10 (patch) | |
tree | 05c64c6f130e07c3ac91281b120227a01c29f6e7 /source/blender/blenkernel/BKE_lib_id.h | |
parent | de09db6b4d132bddbd7c322c8853deeea38131a4 (diff) |
Cleanup: Add basic doc about each `BKE_main` and `BKE_lib` files.
Including expected prefixes for functions in those files.
Part of T72604.
Diffstat (limited to 'source/blender/blenkernel/BKE_lib_id.h')
-rw-r--r-- | source/blender/blenkernel/BKE_lib_id.h | 42 |
1 files changed, 24 insertions, 18 deletions
diff --git a/source/blender/blenkernel/BKE_lib_id.h b/source/blender/blenkernel/BKE_lib_id.h index f3bf2db8f6f..f3a92fba1fb 100644 --- a/source/blender/blenkernel/BKE_lib_id.h +++ b/source/blender/blenkernel/BKE_lib_id.h @@ -21,31 +21,37 @@ /** \file * \ingroup bke + * + * API to manage data-blocks inside of Blender's Main data-base, or as independant runtime-only + * data. + * + * \note `BKE_lib_` files are for operations over data-blocks themselves, although they might + * alter Main as well (when creating/renaming/deleting an ID e.g.). + * + * \section Function Names + * + * \warning Descriptions below is ideal goal, current status of naming does not yet fully follow it + * (this is WIP). + * + * - `BKE_lib_id_` should be used for rather high-level operations, that involve Main database and + * relations with other IDs, and can be considered as 'safe' (as in, in themselves, they leave + * affected IDs/Main in a consistent status). + * - `BKE_lib_libblock_` should be used for lower level operations, that perform some parts of + * `BKE_lib_id_` ones, but will generally not ensure caller that affected data is in a consistent + * state by their own execution alone. + * - `BKE_lib_main_` should be used for operations performed over all IDs of a given Main + * data-base. + * + * \note External code should typically not use `BKE_lib_libblock_` functions, except in some + * specific cases requiring advanced (and potentially dangerous) handling. */ + #ifdef __cplusplus extern "C" { #endif #include "BLI_compiler_attrs.h" -/** - * Naming: BKE_id_ vs BKE_libblock_ - * - * WARNING: description below is ideal goal, current status of naming does not yet - * fully follow it (this is WIP). - * - * - BKE_id_ should be used for rather high-level operations, that involve Main database and - * relations with other IDs, and can be considered as 'safe' - * (as in, in themselves, they leave affected IDs/Main in a consistent status). - * - * - BKE_libblock_ should be used for lower level operations, - * that perform some parts of BKE_id_ ones, but will generally not ensure caller that affected - * data is in a consistent state by their own execution alone. - * - * Consequently, external code should not typically use BKE_libblock_ functions, - * except in some specific cases requiring advanced (and potentially dangerous) handling. - */ - struct GHash; struct ID; struct Library; |