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