From cd48b132ffafc80347a668b3c1cf295abf399f10 Mon Sep 17 00:00:00 2001 From: Bastien Montagne Date: Mon, 10 Feb 2020 15:05:54 +0100 Subject: Cleanup: Add basic doc about each `BKE_main` and `BKE_lib` files. Including expected prefixes for functions in those files. Part of T72604. --- source/blender/blenkernel/BKE_lib_id.h | 42 ++++++++++++++++------------ source/blender/blenkernel/BKE_lib_override.h | 15 ++++++++++ source/blender/blenkernel/BKE_lib_query.h | 12 ++++++++ source/blender/blenkernel/BKE_lib_remap.h | 14 ++++++++++ source/blender/blenkernel/BKE_main.h | 17 +++++++---- source/blender/blenkernel/BKE_main_idmap.h | 10 +++++++ 6 files changed, 87 insertions(+), 23 deletions(-) (limited to 'source/blender/blenkernel') 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; diff --git a/source/blender/blenkernel/BKE_lib_override.h b/source/blender/blenkernel/BKE_lib_override.h index 5cffabd333f..b6db93e1cf0 100644 --- a/source/blender/blenkernel/BKE_lib_override.h +++ b/source/blender/blenkernel/BKE_lib_override.h @@ -22,6 +22,21 @@ /** \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_override_library_` should be used for function affecting a single ID. + * - `BKE_lib_override_library_main_` should be used for function affecting the whole collection + * of IDs in a given Main data-base. */ struct ID; diff --git a/source/blender/blenkernel/BKE_lib_query.h b/source/blender/blenkernel/BKE_lib_query.h index b959b55b1d6..a0abe4320ed 100644 --- a/source/blender/blenkernel/BKE_lib_query.h +++ b/source/blender/blenkernel/BKE_lib_query.h @@ -21,6 +21,18 @@ /** \file * \ingroup bke + * + * API to perform operations over all ID pointers used by a given data-block. + * + * \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_query_` should be used for functions in that file. */ struct ID; diff --git a/source/blender/blenkernel/BKE_lib_remap.h b/source/blender/blenkernel/BKE_lib_remap.h index 18480e7052b..0f39060f2f9 100644 --- a/source/blender/blenkernel/BKE_lib_remap.h +++ b/source/blender/blenkernel/BKE_lib_remap.h @@ -18,7 +18,21 @@ /** \file * \ingroup bke + * + * API to perform remapping from one data-block pointer to another. + * + * \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_remap_libblock_` should be used for functions performing remapping. + * - `BKE_lib_remap_callback_` should be used for functions managing remapping callbacks. */ + #ifdef __cplusplus extern "C" { #endif diff --git a/source/blender/blenkernel/BKE_main.h b/source/blender/blenkernel/BKE_main.h index 744c58401a6..66cbe6d838f 100644 --- a/source/blender/blenkernel/BKE_main.h +++ b/source/blender/blenkernel/BKE_main.h @@ -22,13 +22,20 @@ /** \file * \ingroup bke * \section aboutmain Main struct - * Main is the root of the 'database' of a Blender context. All data - * is stuffed into lists, and all these lists are knotted to here. A - * Blender file is not much more but a binary dump of these - * lists. This list of lists is not serialized itself. + * Main is the root of the 'data-base' of a Blender context. All data is put into lists, and all + * these lists are stored here. * - * Oops... this should be a _types.h file. + * \note A Blender file is not much more than a binary dump of these lists. This list of lists is + * not serialized itself. + * + * \note `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. + * + * \section Function Names + * + * - `BKE_main_` should be used for functions in that file. */ + #include "DNA_listBase.h" #include "BLI_compiler_attrs.h" diff --git a/source/blender/blenkernel/BKE_main_idmap.h b/source/blender/blenkernel/BKE_main_idmap.h index d95f32b162a..b411d34be47 100644 --- a/source/blender/blenkernel/BKE_main_idmap.h +++ b/source/blender/blenkernel/BKE_main_idmap.h @@ -18,6 +18,16 @@ /** \file * \ingroup bke + * + * API to generate and use a mapping from [ID type & name] to [id pointer], within a given Main + * data-base. + * + * \note `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. + * + * \section Function Names + * + * - `BKE_main_idmap_` Should be used for functions in that file. */ #include "BLI_compiler_attrs.h" -- cgit v1.2.3