Docs: formalize naming for generic callbacks in BKE_callbacks.h

Add a doc-string explaining the purpose of each call back and
how they should be used.

Also add a currently unused callback 'POST_FAIL' that is to be used in
cases the action fails - giving script authors, a guarantee that a
call to `pre` will always have a matching `post/post_fail` call.

- D11422: adds a callback that can use 'post_fail'.
- T88696: proposed these conventions.

2 files changed, 57 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,
diff --git a/source/blender/python/intern/bpy_app_handlers.c b/source/blender/python/intern/bpy_app_handlers.c
index a0b543097e6..bc05c51414f 100644
--- a/source/blender/python/intern/bpy_app_handlers.c
+++ b/source/blender/python/intern/bpy_app_handlers.c
@@ -43,6 +43,9 @@ void bpy_app_generic_callback(struct Main *main,
 
 static PyTypeObject BlenderAppCbType;
 
+/**
+ * See `BKE_callbacks.h` #eCbEvent declaration for the policy on naming.
+ */
 static PyStructSequence_Field app_cb_info_fields[] = {
     {"frame_change_pre",
      "Called after frame change for playback and rendering, before any data is evaluated for the "