From 5dc798f2e4886906336be8d3095a3ff8a196c173 Mon Sep 17 00:00:00 2001
From: Campbell Barton <campbell@blender.org>
Date: Wed, 5 Oct 2022 15:30:42 +1100
Subject: Docs: improve doc-strings for blend file IO

- Document the behavior of app-template IO for preferences.
- Add doxy-sections for each kind of blend file IO.
- Clarify BKE_blender_userdef_app_template_data_swap doc-string.
---
 source/blender/blenkernel/BKE_blender.h      |  3 ++-
 source/blender/blenkernel/intern/blendfile.c | 38 ++++++++++++++++++++++++++--
 2 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/source/blender/blenkernel/BKE_blender.h b/source/blender/blenkernel/BKE_blender.h
index b42073eeb9a..940dec2fcd5 100644
--- a/source/blender/blenkernel/BKE_blender.h
+++ b/source/blender/blenkernel/BKE_blender.h
@@ -26,8 +26,9 @@ void BKE_blender_userdef_data_set(struct UserDef *userdef);
 void BKE_blender_userdef_data_set_and_free(struct UserDef *userdef);
 
 /**
- * Write U from userdef.
  * This function defines which settings a template will override for the user preferences.
+ *
+ * \note the order of `userdef_a` & `userdef_b` isn't important as values are simply swapped.
  */
 void BKE_blender_userdef_app_template_data_swap(struct UserDef *userdef_a,
                                                 struct UserDef *userdef_b);
diff --git a/source/blender/blenkernel/intern/blendfile.c b/source/blender/blenkernel/intern/blendfile.c
index bf40d07054d..f5b385b1682 100644
--- a/source/blender/blenkernel/intern/blendfile.c
+++ b/source/blender/blenkernel/intern/blendfile.c
@@ -61,7 +61,7 @@
 #endif
 
 /* -------------------------------------------------------------------- */
-/** \name High Level `.blend` file read/write.
+/** \name Blend File IO (High Level)
  * \{ */
 
 static bool blendfile_or_libraries_versions_atleast(Main *bmain,
@@ -559,6 +559,34 @@ void BKE_blendfile_read_make_empty(bContext *C)
   FOREACH_MAIN_LISTBASE_END;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Blend File IO (Preferences)
+ *
+ * Application Templates
+ * =====================
+ *
+ * When using app-templates, both regular & app-template preferences are used.
+ * Note that "regular" preferences refers to the preferences used with no app-template is active.
+ *
+ * - Reading preferences is performed for both the app-template & regular preferences.
+ *
+ *   The preferences are merged by using some from the app-template and other settings from the
+ *   regular preferences (add-ons from the app-template for example are used),
+ *   undo-memory uses the regular preferences (for e.g.).
+ *
+ * - Writing preferences is performed for both the app-template & regular preferences.
+ *
+ *   Writing unmodified preference (#U) into the regular preferences
+ *   would loose any settings the app-template overrides.
+ *   To keep default settings the regular preferences is read, add-ons etc temporarily swapped
+ *   into #U for writing, then swapped back out so as not to change the run-time preferences.
+ *
+ * \note The function #BKE_blender_userdef_app_template_data_swap determines which settings
+ * the app-template overrides.
+ * \{ */
+
 UserDef *BKE_blendfile_userdef_read(const char *filepath, ReportList *reports)
 {
   BlendFileData *bfd;
@@ -756,6 +784,12 @@ bool BKE_blendfile_userdef_write_all(ReportList *reports)
   return ok;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Blend File IO (WorkSpace)
+ * \{ */
+
 WorkspaceConfigFileData *BKE_blendfile_workspace_config_read(const char *filepath,
                                                              const void *filebuf,
                                                              int filelength,
@@ -818,7 +852,7 @@ void BKE_blendfile_workspace_config_data_free(WorkspaceConfigFileData *workspace
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/** \name Partial `.blend` file save.
+/** \name Blend File Write (Partial)
  * \{ */
 
 void BKE_blendfile_write_partial_begin(Main *bmain_src)
-- 
cgit v1.2.3