RNA: document Python instancing for ID's and RNA types

Document some of the less obvious implications for
re-using Python instances.

1 files changed, 11 insertions, 0 deletions

diff --git a/source/blender/makesrna/intern/rna_internal_types.h b/source/blender/makesrna/intern/rna_internal_types.h
index 01c406104d7..e6ed0f69300 100644
--- a/source/blender/makesrna/intern/rna_internal_types.h
+++ b/source/blender/makesrna/intern/rna_internal_types.h
@@ -545,6 +545,17 @@ struct StructRNA {
   /* function to register/unregister subclasses */
   StructRegisterFunc reg;
   StructUnregisterFunc unreg;
+  /**
+   * Optionally support reusing Python instances for this type.
+   *
+   * Without this, an operator class created for #wmOperatorType.invoke (for example)
+   * would have a different instance passed to the #wmOperatorType.modal callback.
+   * So any variables assigned to `self` from Python would not be available to other callbacks.
+   *
+   * Being able to access the instance also has the advantage that we can invalidate
+   * the Python instance when the data has been removed, see: #BPY_DECREF_RNA_INVALIDATE
+   * so accessing the variables from Python raises an exception instead of crashing.
+   */
   StructInstanceFunc instance;
 
   /* callback to get id properties */