[Bf-blender-cvs] [7be5ca63aee] master: Python API Docs: explain the CANCELLED return code of operators.

[Alexander Gavrilov]

Commit: 7be5ca63aee8de3cfeabdb9bdd8bb5613defd824
Author: Alexander Gavrilov
Date:   Mon Dec 26 14:42:01 2022 +0200
Branches: master
https://developer.blender.org/rB7be5ca63aee8de3cfeabdb9bdd8bb5613defd824

Python API Docs: explain the CANCELLED return code of operators.

The effect of CANCELLED on the undo stack is quite obscure, and
mistakenly using it after doing some changes causes confusing
behavior. It's better to describe it explicitly in the docs.

===================================================================

M	doc/python_api/examples/bpy.ops.py
M	doc/python_api/examples/bpy.types.Operator.5.py
M	doc/python_api/examples/bpy.types.Operator.py

===================================================================

diff --git a/doc/python_api/examples/bpy.ops.py b/doc/python_api/examples/bpy.ops.py
index e8d545fc855..aa51c6c5162 100644
--- a/doc/python_api/examples/bpy.ops.py
+++ b/doc/python_api/examples/bpy.ops.py
@@ -10,8 +10,9 @@ Only keyword arguments can be used to pass operator properties.
 Operators don't have return values as you might expect,
 instead they return a set() which is made up of:
 ``{'RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH'}``.
-Common return values are ``{'FINISHED'}`` and ``{'CANCELLED'}``.
-
+Common return values are ``{'FINISHED'}`` and ``{'CANCELLED'}``, the latter
+meaning that the operator execution was aborted without making any changes or
+saving an undo history entry.
 
 Calling an operator in the wrong context will raise a ``RuntimeError``,
 there is a poll() method to avoid this problem.
diff --git a/doc/python_api/examples/bpy.types.Operator.5.py b/doc/python_api/examples/bpy.types.Operator.5.py
index 0b6035fc3da..6f912f863f1 100644
--- a/doc/python_api/examples/bpy.types.Operator.5.py
+++ b/doc/python_api/examples/bpy.types.Operator.5.py
@@ -44,6 +44,7 @@ class ModalOperator(bpy.types.Operator):
         elif event.type == 'LEFTMOUSE':  # Confirm
             return {'FINISHED'}
         elif event.type in {'RIGHTMOUSE', 'ESC'}:  # Cancel
+            # Revert all changes that have been made
             context.object.location.x = self.init_loc_x
             return {'CANCELLED'}
 
diff --git a/doc/python_api/examples/bpy.types.Operator.py b/doc/python_api/examples/bpy.types.Operator.py
index 41b96ac402f..19cd08b018f 100644
--- a/doc/python_api/examples/bpy.types.Operator.py
+++ b/doc/python_api/examples/bpy.types.Operator.py
@@ -7,9 +7,16 @@ This script shows simple operator which prints a message.
 Since the operator only has an :class:`Operator.execute` function it takes no
 user input.
 
+The function should return ``{'FINISHED'}`` or ``{'CANCELLED'}``, the latter
+meaning that operator execution was aborted without making any changes, and
+saving an undo entry isn't neccesary. If an error is detected after some changes
+have already been made, use the ``{'FINISHED'}`` return code, or the behavior
+of undo will be confusing for the user.
+
 .. note::
 
    Operator subclasses must be registered before accessing them from blender.
+
 """
 import bpy