From f5679838bcfece558e8604b874aa8900460871f2 Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Mon, 13 Dec 2021 14:05:31 +1100
Subject: Docs: document all Global (G) struct members

---
 source/blender/blenkernel/BKE_global.h | 89 ++++++++++++++++++++++++++++------
 1 file changed, 75 insertions(+), 14 deletions(-)

(limited to 'source/blender/blenkernel/BKE_global.h')

diff --git a/source/blender/blenkernel/BKE_global.h b/source/blender/blenkernel/BKE_global.h
index d6cabbc1236..630db07e4d9 100644
--- a/source/blender/blenkernel/BKE_global.h
+++ b/source/blender/blenkernel/BKE_global.h
@@ -37,35 +37,70 @@ struct Main;
 
 typedef struct Global {
 
-  /** Active pointers. */
+  /**
+   * Data for the current active blend file.
+   *
+   * Note that `CTX_data_main(C)` should be used where possible.
+   * Otherwise access via #G_MAIN.
+   */
   struct Main *main;
 
-  /** Strings: last saved */
-  char ima[1024], lib[1024]; /* 1024 = FILE_MAX */
+  /** Last saved location for images. */
+  char ima[1024]; /* 1024 = FILE_MAX */
+  /** Last used location for library link/append. */
+  char lib[1024];
 
   /** When set: `G_MAIN->name` contains valid relative base path. */
   bool relbase_valid;
+  /**
+   * When set:
+   * - Saving writes to `G_MAIN->name` without prompting for a file-path.
+   * - The title-bar displays `G_MAIN->name`.
+   */
   bool save_over;
 
-  /** Strings of recent opened files. */
+  /**
+   * Strings of recently opened files to show in the file menu.
+   * A list of #RecentFile read from #BLENDER_HISTORY_FILE.
+   */
   struct ListBase recent_files;
 
-  /** Has escape been pressed or Ctrl+C pressed in background mode, used for render quit. */
+  /**
+   * Set when Escape been pressed or `Ctrl-C` pressed in background mode.
+   * Used for render quit and some other background tasks such as baking.
+   */
   bool is_break;
 
+  /**
+   * Blender is running without any Windows or OpenGLES context.
+   * Typically set by the `--background` command-line argument.
+   *
+   * Also enabled when build defines `WITH_PYTHON_MODULE` or `WITH_HEADLESS` are set
+   * (which use background mode by definition).
+   */
   bool background;
+
+  /**
+   * Skip reading the startup file and user preferences.
+   * Also disable saving the preferences on exit (see #G_FLAG_USERPREF_NO_SAVE_ON_EXIT),
+   * see via the command line argument: `--factory-startup`.
+   */
   bool factory_startup;
 
+  /**
+   * Set when the user is interactively moving (transforming) content.
+   * see: #G_TRANSFORM_OBJ and related flags.
+   */
   short moving;
 
-  /** To indicate render is busy, prevent render-window events etc. */
+  /** To indicate render is busy, prevent render-window events, animation playback etc. */
   bool is_rendering;
 
   /**
    * Debug value, can be set from the UI and python, used for testing nonstandard features.
    * DO NOT abuse it with generic checks like `if (G.debug_value > 0)`. Do not use it as bitflags.
    * Only precise specific values should be checked for, to avoid unpredictable side-effects.
-   * Please document here the value(s) you are using (or a range of values reserved to some area).
+   * Please document here the value(s) you are using (or a range of values reserved to some area):
    *   * -16384 and below: Reserved for python (add-ons) usage.
    *   *     -1: Disable faster motion paths computation (since 08/2018).
    *   * 1 - 30: EEVEE debug/stats values (01/2018).
@@ -82,24 +117,50 @@ typedef struct Global {
    */
   short debug_value;
 
-  /** Saved to the blend file as #FileGlobal.globalf,
-   * however this is now only used for runtime options. */
+  /**
+   * Saved to the blend file as #FileGlobal.globalf
+   *
+   * \note Currently this is only used for runtime options, adding flags to #G_FLAG_ALL_READFILE
+   * will cause them to be written and read to files.
+   */
   int f;
 
   struct {
-    /** Logging vars (different loggers may use). */
+    /**
+     * Logging vars (different loggers may use).
+     * Set via `--log-level` command line argument.
+     */
     int level;
-    /** FILE handle or use stderr (we own this so close when done). */
+    /**
+     * FILE handle or use `stderr` (we own this so close when done).
+     * Set via `--log-file` command line argument.
+     */
     void *file;
   } log;
 
-  /** debug flag, #G_DEBUG, #G_DEBUG_PYTHON & friends, set python or command line args */
+  /**
+   * Debug flag, #G_DEBUG, #G_DEBUG_PYTHON & friends, set via:
+   * - Command line arguments: `--debug`, `--debug-memory` ... etc.
+   * - Python API: `bpy.app.debug`, `bpy.app.debug_memory` ... etc.
+   */
   int debug;
 
-  /** This variable is written to / read from #FileGlobal.fileflags */
+  /**
+   * Control behavior of file reading/writing.
+   *
+   * This variable is written to / read from #FileGlobal.fileflags.
+   * See: #G_FILE_COMPRESS and related flags.
+   */
   int fileflags;
 
-  /** Message to use when auto execution fails. */
+  /**
+   * Message to show when loading a `.blend` file attempts to execute
+   * a Python script or driver-expression when doing so is disallowed.
+   *
+   * Set when `(G.f & G_FLAG_SCRIPT_AUTOEXEC_FAIL) == 0`,
+   * so users can be alerted to the reason why the file may not be behaving as expected.
+   * Typically Python drivers.
+   */
   char autoexec_fail[200];
 } Global;
 
-- 
cgit v1.2.3