[Bf-blender-cvs] [cd48b132ffa] master: Cleanup: Add basic doc about each `BKE_main` and `BKE_lib` files.

[Bastien Montagne]

Commit: cd48b132ffafc80347a668b3c1cf295abf399f10
Author: Bastien Montagne
Date:   Mon Feb 10 15:05:54 2020 +0100
Branches: master
https://developer.blender.org/rBcd48b132ffafc80347a668b3c1cf295abf399f10

Cleanup: Add basic doc about each `BKE_main` and `BKE_lib` files.

Including expected prefixes for functions in those files.

Part of T72604.

===================================================================

M	source/blender/blenkernel/BKE_lib_id.h
M	source/blender/blenkernel/BKE_lib_override.h
M	source/blender/blenkernel/BKE_lib_query.h
M	source/blender/blenkernel/BKE_lib_remap.h
M	source/blender/blenkernel/BKE_main.h
M	source/blender/blenkernel/BKE_main_idmap.h

===================================================================

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"