[Bf-blender-cvs] [8b6330dfbea] greasepencil-object: Add code documentation

[Falk David]

Commit: 8b6330dfbea6af317b51f89c03bb4c7428543e62
Author: Falk David
Date:   Tue Feb 1 17:22:37 2022 +0100
Branches: greasepencil-object
https://developer.blender.org/rB8b6330dfbea6af317b51f89c03bb4c7428543e62

Add code documentation

Co-authored-by: Yann Lanthony <ylanthony at thespastudios.com>

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

M	source/blender/blenkernel/BKE_gpencil_update_cache.h
M	source/blender/blenkernel/intern/gpencil_update_cache.c

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

diff --git a/source/blender/blenkernel/BKE_gpencil_update_cache.h b/source/blender/blenkernel/BKE_gpencil_update_cache.h
index c8c3e810edb..7ee1542c28d 100644
--- a/source/blender/blenkernel/BKE_gpencil_update_cache.h
+++ b/source/blender/blenkernel/BKE_gpencil_update_cache.h
@@ -83,9 +83,11 @@ typedef struct GPencilUpdateCacheNode {
 } GPencilUpdateCacheNode;
 
 /**
- *
+ * Callback that is called in BKE_gpencil_traverse_update_cache at each level.
+ * \param cache: The cache at this level.
+ * \param user_data: Pointer to the user_data passed to BKE_gpencil_traverse_update_cache.
  */
-typedef bool (*GPencilUpdateCacheIter_Cb)(struct GPencilUpdateCache *cache, void *user_data);
+typedef bool (*GPencilUpdateCacheIter_Cb)(GPencilUpdateCache *cache, void *user_data);
 
 typedef struct GPencilUpdateCacheTraverseSettings {
   /* Callbacks for the update cache traversal. Callback with index 0 is for layers, 1 for frames
@@ -93,28 +95,54 @@ typedef struct GPencilUpdateCacheTraverseSettings {
   GPencilUpdateCacheIter_Cb update_cache_cb[3];
 } GPencilUpdateCacheTraverseSettings;
 
-struct GPencilUpdateCache *BKE_gpencil_create_update_cache_data(void *data, bool full_copy);
+/**
+ * Allocates a new GPencilUpdateCache and populates it.
+ * \param data: A data pointer to populate the initial cache with.
+ * \param full_copy: If true, will mark this update cache as a full copy
+ * (GP_UPDATE_NODE_FULL_COPY). If false, it will be marked as a struct copy
+ * (GP_UPDATE_NODE_STRUCT_COPY).
+ */
+GPencilUpdateCache *BKE_gpencil_create_update_cache(void *data, bool full_copy);
 
 /**
- * Traverse an update cache and execute callbacks at each level.
+ * Traverses an update cache and executes callbacks at each level.
  * \param cache: The update cache to traverse.
  * \param ts: The traversal settings. This stores the callbacks that are called at each level.
  * \param user_data: Custom data passed to each callback.
  */
-void BKE_gpencil_traverse_update_cache(struct GPencilUpdateCache *cache,
+void BKE_gpencil_traverse_update_cache(GPencilUpdateCache *cache,
                                        GPencilUpdateCacheTraverseSettings *ts,
                                        void *user_data);
 
+/**
+ * Tags an element (bGPdata, bGPDlayer, bGPDframe, or bGPDstroke) and all of its containing data to
+ * be updated in the next update-on-write operation.
+ *
+ * The function assumes that when a parameter is NULL all of the following parameters are NULL too.
+ * E.g. in order to tag a layer (gpl), the parameters would *have* to be (gpd, gpl, NULL, NULL).
+ */
 void BKE_gpencil_tag_full_update(struct bGPdata *gpd,
                                  struct bGPDlayer *gpl,
                                  struct bGPDframe *gpf,
                                  struct bGPDstroke *gps);
 
+/**
+ * Tags an element (bGPdata, bGPDlayer, bGPDframe, or bGPDstroke) to be updated in the next
+ * update-on-write operation. This function will not update any of the containing data, only the
+ * struct itself.
+ *
+ * The function assumes that when a parameter is NULL all of the following parameters are NULL too.
+ * E.g. in order to tag a layer (gpl), the parameters would *have* to be (gpd, gpl, NULL, NULL).
+ */
 void BKE_gpencil_tag_struct_update(struct bGPdata *gpd,
                                    struct bGPDlayer *gpl,
                                    struct bGPDframe *gpf,
                                    struct bGPDstroke *gps);
 
+/**
+ * Frees the GPencilUpdateCache on the gpd->runtime. This will not free the data that the cache
+ * node might point to. It assumes that the cache does not own the data.
+ */
 void BKE_gpencil_free_update_cache(struct bGPdata *gpd);
 
 #ifdef __cplusplus
diff --git a/source/blender/blenkernel/intern/gpencil_update_cache.c b/source/blender/blenkernel/intern/gpencil_update_cache.c
index 5e8ba2ad61e..c47ee9a621f 100644
--- a/source/blender/blenkernel/intern/gpencil_update_cache.c
+++ b/source/blender/blenkernel/intern/gpencil_update_cache.c
@@ -240,7 +240,7 @@ static void gpencil_traverse_update_cache_ex(GPencilUpdateCache *parent_cache,
  *
  * \{ */
 
-GPencilUpdateCache *BKE_gpencil_create_update_cache_data(void *data, bool full_copy)
+GPencilUpdateCache *BKE_gpencil_create_update_cache(void *data, bool full_copy)
 {
   return update_cache_alloc(
       0, full_copy ? GP_UPDATE_NODE_FULL_COPY : GP_UPDATE_NODE_STRUCT_COPY, data);