Comments: document memory management for `BPyPropStore`

1 files changed, 33 insertions, 4 deletions

diff --git a/source/blender/python/intern/bpy_props.c b/source/blender/python/intern/bpy_props.c
index b6149175c91..e4e6b3ea8f2 100644
--- a/source/blender/python/intern/bpy_props.c
+++ b/source/blender/python/intern/bpy_props.c
@@ -198,15 +198,44 @@ static const EnumPropertyItem property_subtype_array_items[] = {
  * \{ */
 
 /**
- * Slots for #PyObject slots stored in #PropertyRNA.py_data (these hold a reference).
- * #bpy_prop_callback_free_py_data manages decrementing.
+ * Store #PyObject data for a dynamically defined property.
+ * Currently this is only used to store call-back functions.
+ * Properties that don't use custom-callbacks wont allocate this struct.
+ *
+ * Memory/Reference Management
+ * ---------------------------
+ *
+ * This struct adds/removes the user-count of each #PyObject it references,
+ * it's needed in case the function is removed from the class (unlikely but possible),
+ * also when an annotation evaluates to a `lambda` with Python 3.10 and newer e.g: T86332.
+ *
+ * Pointers to this struct are held in:
+ *
+ * - #PropertyRNA.py_data (owns the memory).
+ *   Freed when the RNA property is freed.
+ *
+ * - #g_bpy_prop_store_list (borrows the memory)
+ *   Having a global list means the users can be visited by the GC and cleared on exit.
+ *
+ *   This list can't be used for freeing as #BPyPropStore doesn't hold a #PropertyRNA back-pointer,
+ *   (while it could be supported it would only complicate things).
+ *
+ *   All RNA properties are freed after Python has been shut-down.
+ *   At that point Python user counts can't be touched and must have already been dealt with.
+ *
+ * Decrementing users is handled by:
+ *
+ * - #bpy_prop_py_data_remove manages decrementing at run-time (when a property is removed),
+ *
+ * - #BPY_rna_props_clear_all does this on exit for all dynamic properties.
  */
 struct BPyPropStore {
   struct BPyPropStore *next, *prev;
 
   /**
-   * Only store #PyObject types, can be cast to an an array and operated on.
-   * NULL members are ignored/skipped. */
+   * Only store #PyObject types, so this member can be cast to an array and iterated over.
+   * NULL members are skipped.
+   */
   struct {
     /** Wrap: `RNA_def_property_*_funcs` (depending on type). */
     PyObject *get_fn;