Cleanup: Add basic doc about each `BKE_main` and `BKE_lib` files.
Including expected prefixes for functions in those files. Part of T72604.
This commit is contained in:
parent
de09db6b4d
commit
cd48b132ff
|
@ -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;
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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;
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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"
|
||||
|
|
|
@ -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"
|
||||
|
|
Loading…
Reference in New Issue