1 files changed, 54 insertions, 5 deletions
diff --git a/source/blender/blenkernel/BKE_callbacks.h b/source/blender/blenkernel/BKE_callbacks.h
index f04b5e45720..ef2a0ed34a0 100644
--- a/source/blender/blenkernel/BKE_callbacks.h
+++ b/source/blender/blenkernel/BKE_callbacks.h
@@ -30,11 +30,60 @@ struct Main;
 struct PointerRNA;
 
 /**
- * Common suffix uses:
- * - ``_PRE/_POST``:
- *   For handling discrete non-interactive events.
- * - ``_INIT/_COMPLETE/_CANCEL``:
- *   For handling jobs (which may in turn cause other handlers to be called).
+   Callbacks for One Off Actions
+ * =============================
+ *
+ * - `{ACTION}` use in cases where only a single callback is required,
+ *   `VERSION_UPDATE` and `RENDER_STATS` for example.
+ *
+ * \note avoid single callbacks if there is a chance `PRE/POST` are useful to differentiate
+ * since renaming callbacks may break Python scripts.
+ *
+ * Callbacks for Common Actions
+ * ============================
+ *
+ * - `{ACTION}_PRE` run before the action.
+ * - `{ACTION}_POST` run after the action.
+ *
+ * Optional Additional Callbacks
+ * -----------------------------
+ *
+ * - `{ACTION}_INIT` when the handler may manipulate the context used to run the action.
+ *
+ *   Examples where `INIT` functions may be useful are:
+ *
+ *   - When rendering, an `INIT` function may change the camera or render settings,
+ *     things which a `PRE` function can't support as this information has already been used.
+ *   - When saving an `INIT` function could temporarily change the preferences.
+ *
+ * - `{ACTION}_POST_FAIL` should be included if the action may fail.
+ *
+ *   Use this so a call to the `PRE` callback always has a matching call to `POST` or `POST_FAIL`.
+ *
+ * \note in most cases only `PRE/POST` are required.
+ *
+ * Callbacks for Background/Modal Tasks
+ * ====================================
+ *
+ * - `{ACTION}_INIT`
+ * - `{ACTION}_COMPLETE` when a background job has finished.
+ * - `{ACTION}_CANCEL` When a background job is canceled partway through.
+ *
+ *   While cancellation may be caused by any number of reasons, common causes may include:
+ *
+ *   - Explicit user cancellation.
+ *   - Exiting Blender.
+ *   - Failure to acquire resources (such as disk-full, out of memory ... etc).
+ *
+ * \note `PRE/POST` handlers may be used along side modal task handlers
+ * as is the case for rendering, where rendering an animation uses modal task handlers,
+ * rendering a single frame has `PRE/POST` handlers.
+ *
+ * Python Access
+ * =============
+ *
+ * All callbacks here must be exposed via the Python module `bpy.app.handlers`,
+ * see `bpy_app_handlers.c`.
  */
 typedef enum {
   BKE_CB_EVT_FRAME_CHANGE_PRE,