Cleanup/document BKE_blender_copybuffer.

* Rename the 'copy' functions to make it clear they belong to the same
  'group' and are to be used together.
* Fix `flag` parameter of `BKE_copybuffer_paste` being a short instead
  of an int.
* Improve documentation.

5 files changed, 48 insertions, 20 deletions

diff --git a/source/blender/blenkernel/BKE_blender_copybuffer.h b/source/blender/blenkernel/BKE_blender_copybuffer.h
index 1dd6d495276..4dd7145e66d 100644
--- a/source/blender/blenkernel/BKE_blender_copybuffer.h
+++ b/source/blender/blenkernel/BKE_blender_copybuffer.h
@@ -31,16 +31,18 @@ struct ReportList;
 struct bContext;
 
 /* copybuffer (wrapper for BKE_blendfile_write_partial) */
-void BKE_copybuffer_begin(struct Main *bmain_src);
-void BKE_copybuffer_tag_ID(struct ID *id);
-bool BKE_copybuffer_save(struct Main *bmain_src, const char *filename, struct ReportList *reports);
+void BKE_copybuffer_copy_begin(struct Main *bmain_src);
+void BKE_copybuffer_copy_tag_ID(struct ID *id);
+bool BKE_copybuffer_copy_end(struct Main *bmain_src,
+                             const char *filename,
+                             struct ReportList *reports);
 bool BKE_copybuffer_read(struct Main *bmain_dst,
                          const char *libname,
                          struct ReportList *reports,
                          const uint64_t id_types_mask);
 int BKE_copybuffer_paste(struct bContext *C,
                          const char *libname,
-                         const short flag,
+                         const int flag,
                          struct ReportList *reports,
                          const uint64_t id_types_mask);
 
diff --git a/source/blender/blenkernel/intern/blender_copybuffer.c b/source/blender/blenkernel/intern/blender_copybuffer.c
index 9c9f898afef..f8b943d3479 100644
--- a/source/blender/blenkernel/intern/blender_copybuffer.c
+++ b/source/blender/blenkernel/intern/blender_copybuffer.c
@@ -57,20 +57,26 @@
 /** \name Copy/Paste `.blend`, partial saves.
  * \{ */
 
-void BKE_copybuffer_begin(Main *bmain_src)
+/** Initialize a copy operation. */
+void BKE_copybuffer_copy_begin(Main *bmain_src)
 {
   BKE_blendfile_write_partial_begin(bmain_src);
 }
 
-void BKE_copybuffer_tag_ID(ID *id)
+/** Mark an ID to be copied. Should only be called after a call to #BKE_copybuffer_copy_begin. */
+void BKE_copybuffer_copy_tag_ID(ID *id)
 {
   BKE_blendfile_write_partial_tag_ID(id, true);
 }
 
 /**
- * \return Success.
+ * Finalize a copy operation into given .blend file 'buffer'.
+ *
+ * \param filename: Full path to the .blend file used as copy/paste buffer.
+ *
+ * \return true on success, false otherwise.
  */
-bool BKE_copybuffer_save(Main *bmain_src, const char *filename, ReportList *reports)
+bool BKE_copybuffer_copy_end(Main *bmain_src, const char *filename, ReportList *reports)
 {
   const int write_flags = 0;
   const eBLO_WritePathRemap remap_mode = BLO_WRITE_PATH_REMAP_RELATIVE;
@@ -82,6 +88,16 @@ bool BKE_copybuffer_save(Main *bmain_src, const char *filename, ReportList *repo
   return retval;
 }
 
+/**
+ * Paste datablocks from the given .blend file 'buffer' (i.e. append them).
+ *
+ * Unlike #BKE_copybuffer_paste, it does not perform any instantiation of collections/objects/etc.
+ *
+ * \param libname: Full path to the .blend file used as copy/paste buffer.
+ * \param id_types_mask: Only directly link IDs of those types from the given .blend file buffer.
+ *
+ * \return true on success, false otherwise.
+ */
 bool BKE_copybuffer_read(Main *bmain_dst,
                          const char *libname,
                          ReportList *reports,
@@ -116,12 +132,22 @@ bool BKE_copybuffer_read(Main *bmain_dst,
 }
 
 /**
- * \return Number of IDs directly pasted from the buffer
- * (does not includes indirectly pulled out ones).
+ * Paste datablocks from the given .blend file 'buffer'  (i.e. append them).
+ *
+ * Similar to #BKE_copybuffer_read, but also handles instantiation of collections/objects/etc.
+ *
+ * \param libname: Full path to the .blend file used as copy/paste buffer.
+ * \param flag: A combination of #eBLOLibLinkFlags and ##eFileSel_Params_Flag to control
+ *              link/append behavior.
+ *              \note: Ignores #FILE_LINK flag, since it always appends IDs.
+ * \param id_types_mask: Only directly link IDs of those types from the given .blend file buffer.
+ *
+ * \return Number of IDs directly pasted from the buffer (does not includes indirectly linked
+ * ones).
  */
 int BKE_copybuffer_paste(bContext *C,
                          const char *libname,
-                         const short flag,
+                         const int flag,
                          ReportList *reports,
                          const uint64_t id_types_mask)
 {
diff --git a/source/blender/editors/armature/pose_transform.c b/source/blender/editors/armature/pose_transform.c
index 279f79ac44b..70d6fa93104 100644
--- a/source/blender/editors/armature/pose_transform.c
+++ b/source/blender/editors/armature/pose_transform.c
@@ -797,13 +797,13 @@ static int pose_copy_exec(bContext *C, wmOperator *op)
   BLI_addtail(&temp_bmain->objects, &ob_copy);
   BLI_addtail(&temp_bmain->armatures, &arm_copy);
   /* begin copy buffer on a temp bmain. */
-  BKE_copybuffer_begin(temp_bmain);
+  BKE_copybuffer_copy_begin(temp_bmain);
   /* Store the whole object to the copy buffer because pose can't be
    * existing on its own.
    */
-  BKE_copybuffer_tag_ID(&ob_copy.id);
+  BKE_copybuffer_copy_tag_ID(&ob_copy.id);
   BLI_join_dirfile(str, sizeof(str), BKE_tempdir_base(), "copybuffer_pose.blend");
-  BKE_copybuffer_save(temp_bmain, str, op->reports);
+  BKE_copybuffer_copy_end(temp_bmain, str, op->reports);
   /* We clear the lists so no datablocks gets freed,
    * This is required because objects in temp bmain shares same pointers
    * as the real ones.
diff --git a/source/blender/editors/space_outliner/outliner_edit.c b/source/blender/editors/space_outliner/outliner_edit.c
index 738db28a2b6..e449e4a609b 100644
--- a/source/blender/editors/space_outliner/outliner_edit.c
+++ b/source/blender/editors/space_outliner/outliner_edit.c
@@ -763,7 +763,7 @@ static int outliner_id_copy_tag(SpaceOutliner *space_outliner, ListBase *tree)
     if (tselem->flag & TSE_SELECTED && ELEM(tselem->type, TSE_SOME_ID, TSE_LAYER_COLLECTION)) {
       ID *id = tselem->id;
       if (!(id->tag & LIB_TAG_DOIT)) {
-        BKE_copybuffer_tag_ID(tselem->id);
+        BKE_copybuffer_copy_tag_ID(tselem->id);
         num_ids++;
       }
     }
@@ -781,7 +781,7 @@ static int outliner_id_copy_exec(bContext *C, wmOperator *op)
   SpaceOutliner *space_outliner = CTX_wm_space_outliner(C);
   char str[FILE_MAX];
 
-  BKE_copybuffer_begin(bmain);
+  BKE_copybuffer_copy_begin(bmain);
 
   const int num_ids = outliner_id_copy_tag(space_outliner, &space_outliner->tree);
   if (num_ids == 0) {
@@ -790,7 +790,7 @@ static int outliner_id_copy_exec(bContext *C, wmOperator *op)
   }
 
   BLI_join_dirfile(str, sizeof(str), BKE_tempdir_base(), "copybuffer.blend");
-  BKE_copybuffer_save(bmain, str, op->reports);
+  BKE_copybuffer_copy_end(bmain, str, op->reports);
 
   BKE_reportf(op->reports, RPT_INFO, "Copied %d selected data-block(s)", num_ids);
 
diff --git a/source/blender/editors/space_view3d/view3d_ops.c b/source/blender/editors/space_view3d/view3d_ops.c
index eb8c043319c..823aa3b6643 100644
--- a/source/blender/editors/space_view3d/view3d_ops.c
+++ b/source/blender/editors/space_view3d/view3d_ops.c
@@ -63,19 +63,19 @@ static int view3d_copybuffer_exec(bContext *C, wmOperator *op)
   char str[FILE_MAX];
   int num_copied = 0;
 
-  BKE_copybuffer_begin(bmain);
+  BKE_copybuffer_copy_begin(bmain);
 
   /* context, selection, could be generalized */
   CTX_DATA_BEGIN (C, Object *, ob, selected_objects) {
     if ((ob->id.tag & LIB_TAG_DOIT) == 0) {
-      BKE_copybuffer_tag_ID(&ob->id);
+      BKE_copybuffer_copy_tag_ID(&ob->id);
       num_copied++;
     }
   }
   CTX_DATA_END;
 
   BLI_join_dirfile(str, sizeof(str), BKE_tempdir_base(), "copybuffer.blend");
-  BKE_copybuffer_save(bmain, str, op->reports);
+  BKE_copybuffer_copy_end(bmain, str, op->reports);
 
   BKE_reportf(op->reports, RPT_INFO, "Copied %d selected object(s)", num_copied);