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.

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.

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'}
 

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