Cleanup: correct/clarify PlayAnim comments

2 files changed, 22 insertions, 5 deletions

diff --git a/source/blender/windowmanager/intern/wm_playanim.c b/source/blender/windowmanager/intern/wm_playanim.c
index 169e1ed8940..3aeb2f35c2f 100644
--- a/source/blender/windowmanager/intern/wm_playanim.c
+++ b/source/blender/windowmanager/intern/wm_playanim.c
@@ -97,6 +97,13 @@ static AUD_Device *audio_device = NULL;
 struct PlayState;
 static void playanim_window_zoom(struct PlayState *ps, const float zoom_offset);
 
+/**
+ * The current state of the player.
+ *
+ * \warning Don't store results of parsing command-line arguments
+ * in this struct if they need to persist across playing back different
+ * files as these will be cleared when playing other files (drag & drop).
+ */
 typedef struct PlayState {
 
   /** Window and viewport size. */
@@ -124,7 +131,12 @@ typedef struct PlayState {
   bool wait2;
   /** Playback stopped state once stop/start variables have been handled. */
   bool stopped;
-  /** When disabled exit the player. */
+  /**
+   * When disabled the current animation will exit,
+   * after this either the application exits or a new animation window is opened.
+   *
+   * This is used so drag & drop can load new files which setup a newly created animation window.
+   */
   bool go;
   /** True when waiting for images to load. */
   bool loading;
@@ -1386,7 +1398,9 @@ static void playanim_window_zoom(PlayState *ps, const float zoom_offset)
   GHOST_SetClientSize(g_WS.ghost_window, sizex, sizey);
 }
 
-/* return path for restart */
+/**
+ * \return The a path used to restart the animation player or NULL to exit.
+ */
 static char *wm_main_playanim_intern(int argc, const char **argv)
 {
   struct ImBuf *ibuf = NULL;
@@ -1426,6 +1440,7 @@ static char *wm_main_playanim_intern(int argc, const char **argv)
           IMB_colormanagement_role_colorspace_name_get(COLOR_ROLE_DEFAULT_BYTE));
   IMB_colormanagement_init_default_view_settings(&ps.view_settings, &ps.display_settings);
 
+  /* Skip the first argument which is assumed to be '-a' (used to launch this player). */
   while (argc > 1) {
     if (argv[1][0] == '-') {
       switch (argv[1][1]) {
diff --git a/source/creator/creator_args.c b/source/creator/creator_args.c
index 9c7b7dc3f34..36fdaef507b 100644
--- a/source/creator/creator_args.c
+++ b/source/creator/creator_args.c
@@ -1195,15 +1195,17 @@ static const char arg_handle_playback_mode_doc[] =
     "\t\tZero disables (clamping to a fixed number of frames instead).";
 static int arg_handle_playback_mode(int argc, const char **argv, void *UNUSED(data))
 {
-  /* not if -b was given first */
+  /* Ignore the animation player if `-b` was given first. */
   if (G.background == 0) {
 #  ifdef WITH_FFMPEG
     /* Setup FFmpeg with current debug flags. */
     IMB_ffmpeg_init();
 #  endif
 
-    WM_main_playanim(argc, argv); /* not the same argc and argv as before */
-    exit(0);                      /* 2.4x didn't do this */
+    /* This function knows to skip this argument ('-a'). */
+    WM_main_playanim(argc, argv);
+
+    exit(0);
   }
 
   return -2;