Cleanup: update sections for wm_files.c

source/blender/windowmanager/intern/wm_files.c

@@ -141,11 +141,37 @@ static void wm_history_file_free(RecentFile *recent);
 static void wm_history_file_update(void);
 static void wm_history_file_write(void);
 
-/* To be able to read files without windows closing, opening, moving
+/* -------------------------------------------------------------------- */
+/** \name Misc Utility Functions
+ * \{ */
+
+void WM_file_tag_modified(void)
+{
+  wmWindowManager *wm = G_MAIN->wm.first;
+  if (wm->file_saved) {
+    wm->file_saved = 0;
+    /* notifier that data changed, for save-over warning or header */
+    WM_main_add_notifier(NC_WM | ND_DATACHANGED, NULL);
+  }
+}
+
+bool wm_file_or_image_is_modified(const Main *bmain, const wmWindowManager *wm)
+{
+  return !wm->file_saved || ED_image_should_save_modified(bmain);
+}
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Window Matching for File Reading
+ * \{ */
+
+/**
+ * To be able to read files without windows closing, opening, moving
  * we try to prepare for worst case:
  * - active window gets active screen from file
  * - restoring the screens from non-active windows
- * Best case is all screens match, in that case they get assigned to proper window
+ * Best case is all screens match, in that case they get assigned to proper window.
  */
 static void wm_window_match_init(bContext *C, ListBase *wmlist)
 {
@@ -355,6 +381,12 @@ static void wm_window_match_do(bContext *C,
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Preferences Initialization & Versioning
+ * \{ */
+
 /* in case UserDef was read, we re-initialize all, and do versioning */
 static void wm_init_userdef(Main *bmain)
 {
@@ -389,6 +421,15 @@ static void wm_init_userdef(Main *bmain)
 #  define BKE_READ_EXOTIC_OK_OTHER 1 /* other supported formats */
 #endif
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Read Exotic File Formats
+ *
+ * Currently only supports '.blend' files,
+ * we could support registering other file formats and their loaders.
+ * \{ */
+
 /* intended to check for non-blender formats but for now it only reads blends */
 static int wm_read_exotic(const char *name)
 {
@@ -441,6 +482,12 @@ static int wm_read_exotic(const char *name)
   return retval;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Read Blend-File Shared Utilities
+ * \{ */
+
 void WM_file_autoexec_init(const char *filepath)
 {
   if (G.f & G_FLAG_SCRIPT_OVERRIDE_PREF) {
@@ -623,6 +670,12 @@ static void wm_file_read_post(bContext *C,
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Read Main Blend-File API
+ * \{ */
+
 bool WM_file_read(bContext *C, const char *filepath, ReportList *reports)
 {
   /* assume automated tasks with background, don't write recent file list */
@@ -766,6 +819,12 @@ const char *WM_init_state_app_template_get(void)
   return wm_init_state_app_template.override ? wm_init_state_app_template.app_template : NULL;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Read Startup & Preferences Blend-File API
+ * \{ */
+
 /**
  * Called on startup, (context entirely filled with NULLs)
  * or called for 'New File' both startup.blend and userpref.blend are checked.
@@ -1101,7 +1160,7 @@ void wm_homefile_read(bContext *C,
 }
 
 /* -------------------------------------------------------------------- */
-/** \name WM History File API
+/** \name Blend-File History API
  * \{ */
 
 void wm_history_file_read(void)
@@ -1230,7 +1289,7 @@ static void wm_history_file_update(void)
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/** \name Save Main .blend File (internal)
+/** \name Save Main Blend-File (internal)
  * \{ */
 
 /* screen can be NULL */
@@ -1654,18 +1713,8 @@ void wm_open_init_use_scripts(wmOperator *op, bool use_prefs)
 
 /** \} */
 
-void WM_file_tag_modified(void)
-{
-  wmWindowManager *wm = G_MAIN->wm.first;
-  if (wm->file_saved) {
-    wm->file_saved = 0;
-    /* notifier that data changed, for save-over warning or header */
-    WM_main_add_notifier(NC_WM | ND_DATACHANGED, NULL);
-  }
-}
-
 /* -------------------------------------------------------------------- */
-/** \name Preferences/startup save & load.
+/** \name Startup File Save Operator
  * \{ */
 
 /**
@@ -1730,6 +1779,12 @@ void WM_OT_save_homefile(wmOperatorType *ot)
   ot->exec = wm_homefile_write_exec;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Add Auto-Execution Path Operator
+ * \{ */
+
 static int wm_userpref_autoexec_add_exec(bContext *UNUSED(C), wmOperator *UNUSED(op))
 {
   bPathCompare *path_cmp = MEM_callocN(sizeof(bPathCompare), "bPathCompare");
@@ -1749,6 +1804,12 @@ void WM_OT_userpref_autoexec_path_add(wmOperatorType *ot)
   ot->flag = OPTYPE_INTERNAL;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Remove Auto-Execution Path Operator
+ * \{ */
+
 static int wm_userpref_autoexec_remove_exec(bContext *UNUSED(C), wmOperator *op)
 {
   const int index = RNA_int_get(op->ptr, "index");
@@ -1773,6 +1834,12 @@ void WM_OT_userpref_autoexec_path_remove(wmOperatorType *ot)
   RNA_def_int(ot->srna, "index", 0, 0, INT_MAX, "Index", "", 0, 1000);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Write Preferences Operator
+ * \{ */
+
 /* Only save the prefs block. operator entry */
 static int wm_userpref_write_exec(bContext *C, wmOperator *op)
 {
@@ -1796,6 +1863,12 @@ void WM_OT_save_userpref(wmOperatorType *ot)
   ot->exec = wm_userpref_write_exec;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Read Preferences Operator
+ * \{ */
+
 /**
  * When reading preferences, there are some exceptions for values which are reset.
  */
@@ -1924,6 +1997,12 @@ void WM_OT_read_factory_userpref(wmOperatorType *ot)
   ot->exec = wm_userpref_read_exec;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Read File History Operator
+ * \{ */
+
 static int wm_history_file_read_exec(bContext *UNUSED(C), wmOperator *UNUSED(op))
 {
   ED_file_read_bookmarks();
@@ -1944,6 +2023,14 @@ void WM_OT_read_history(wmOperatorType *ot)
   ot->flag = OPTYPE_INTERNAL;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Read Startup & Preferences Operator
+ *
+ * Both #WM_OT_read_homefile & #WM_OT_read_factory_settings.
+ * \{ */
+
 static int wm_homefile_read_exec(bContext *C, wmOperator *op)
 {
   const bool use_factory_settings = (STREQ(op->type->idname, "WM_OT_read_factory_settings"));
@@ -2469,7 +2556,7 @@ void WM_OT_revert_mainfile(wmOperatorType *ot)
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/** \name Recover last session & auto-save.
+/** \name Recover Last Session Operator
  * \{ */
 
 void WM_recover_last_session(bContext *C, ReportList *reports)
@@ -2513,6 +2600,12 @@ void WM_OT_recover_last_session(wmOperatorType *ot)
   ot->exec = wm_recover_last_session_exec;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Auto-Save Main .blend File Operator
+ * \{ */
+
 static int wm_recover_auto_save_exec(bContext *C, wmOperator *op)
 {
   char filepath[FILE_MAX];
@@ -2567,6 +2660,8 @@ void WM_OT_recover_auto_save(wmOperatorType *ot)
 
 /* -------------------------------------------------------------------- */
 /** \name Save Main .blend File Operator
+ *
+ * Both #WM_OT_save_as_mainfile & #WM_OT_save_mainfile.
  * \{ */
 
 static void wm_filepath_default(char *filepath)
@@ -2793,7 +2888,7 @@ void WM_OT_save_mainfile(wmOperatorType *ot)
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/** \name Auto-execution of scripts warning popup
+/** \name Auto Script Execution Warning Dialog
  * \{ */
 
 static void wm_block_autorun_warning_ignore(bContext *C, void *arg_block, void *UNUSED(arg))
@@ -2995,8 +3090,11 @@ void wm_test_autorun_warning(bContext *C)
   }
 }
 
-/* Close File Dialog
+/** \} */
- *************************************/
+
+/* -------------------------------------------------------------------- */
+/** \name Close File Dialog
+ * \{ */
 
 static char save_images_when_file_is_closed = true;
 
@@ -3262,9 +3360,4 @@ void wm_close_file_dialog(bContext *C, wmGenericCallback *post_action)
   }
 }
 
-bool wm_file_or_image_is_modified(const Main *bmain, const wmWindowManager *wm)
-{
-  return !wm->file_saved || ED_image_should_save_modified(bmain);
-}
-
 /** \} */