From edf244cbf70d569484b937f58aa9fd69b4243bd5 Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Thu, 28 Jun 2012 08:17:28 +0000
Subject: [PATCH] document calling operators with undo enabled.

---
 doc/python_api/examples/bpy.ops.1.py | 27 +++++++++++----------------
 doc/python_api/examples/bpy.ops.2.py | 27 ++++++++++++++++-----------
 doc/python_api/examples/bpy.ops.py   | 22 +++++++++++++++++++++-
 3 files changed, 48 insertions(+), 28 deletions(-)

diff --git a/doc/python_api/examples/bpy.ops.1.py b/doc/python_api/examples/bpy.ops.1.py
index f43be2b0f63..a00dbdafb90 100644
--- a/doc/python_api/examples/bpy.ops.1.py
+++ b/doc/python_api/examples/bpy.ops.1.py
@@ -1,22 +1,17 @@
 """
-Execution Context
-+++++++++++++++++
+Overriding Context
+------------------
 
-When calling an operator you may want to pass the execution context.
+It is possible to override context members that the operator sees, so that they
+act on specified rather than the selected or active data, or to execute an
+operator in the different part of the user interface.
 
-This determines the context thats given to the operator to run in, and weather
-invoke() is called or execute().
-
-'EXEC_DEFAULT' is used by default but you may want the operator to take user
-interaction with 'INVOKE_DEFAULT'.
-
-The execution context is as a non keyword, string argument in:
-('INVOKE_DEFAULT', 'INVOKE_REGION_WIN', 'INVOKE_REGION_CHANNELS',
-'INVOKE_REGION_PREVIEW', 'INVOKE_AREA', 'INVOKE_SCREEN', 'EXEC_DEFAULT',
-'EXEC_REGION_WIN', 'EXEC_REGION_CHANNELS', 'EXEC_REGION_PREVIEW', 'EXEC_AREA',
-'EXEC_SCREEN')
+The context overrides are passed as a dictionary, with keys matching the context
+member names in bpy.context. For example to override bpy.context.active_object,
+you would pass {'active_object': object}.
 """
 
-# group add popup
+# remove all objects in scene rather than the selected ones
 import bpy
-bpy.ops.object.group_instance_add('INVOKE_DEFAULT')
+override = {'selected_bases': list(bpy.context.scene.object_bases)}
+bpy.ops.object.delete(override)
diff --git a/doc/python_api/examples/bpy.ops.2.py b/doc/python_api/examples/bpy.ops.2.py
index 575d020a5a0..01e7dc1902e 100644
--- a/doc/python_api/examples/bpy.ops.2.py
+++ b/doc/python_api/examples/bpy.ops.2.py
@@ -1,17 +1,22 @@
 """
-Overriding Context
-++++++++++++++++++
+Execution Context
+-----------------
 
-It is possible to override context members that the operator sees, so that they
-act on specified rather than the selected or active data, or to execute an
-operator in the different part of the user interface.
+When calling an operator you may want to pass the execution context.
 
-The context overrides are passed as a dictionary, with keys matching the context
-member names in bpy.context. For example to override bpy.context.active_object,
-you would pass {'active_object': object}.
+This determines the context thats given to the operator to run in, and weather
+invoke() is called or execute().
+
+'EXEC_DEFAULT' is used by default but you may want the operator to take user
+interaction with 'INVOKE_DEFAULT'.
+
+The execution context is as a non keyword, string argument in:
+('INVOKE_DEFAULT', 'INVOKE_REGION_WIN', 'INVOKE_REGION_CHANNELS',
+'INVOKE_REGION_PREVIEW', 'INVOKE_AREA', 'INVOKE_SCREEN', 'EXEC_DEFAULT',
+'EXEC_REGION_WIN', 'EXEC_REGION_CHANNELS', 'EXEC_REGION_PREVIEW', 'EXEC_AREA',
+'EXEC_SCREEN')
 """
 
-# remove all objects in scene rather than the selected ones
+# group add popup
 import bpy
-override = {'selected_bases': list(bpy.context.scene.object_bases)}
-bpy.ops.object.delete(override)
+bpy.ops.object.group_instance_add('INVOKE_DEFAULT')
\ No newline at end of file
diff --git a/doc/python_api/examples/bpy.ops.py b/doc/python_api/examples/bpy.ops.py
index 20e8773652d..9964ad915bf 100644
--- a/doc/python_api/examples/bpy.ops.py
+++ b/doc/python_api/examples/bpy.ops.py
@@ -1,6 +1,6 @@
 """
 Calling Operators
-+++++++++++++++++
+-----------------
 
 Provides python access to calling operators, this includes operators written in
 C, Python or Macros.
@@ -18,6 +18,26 @@ there is a poll() method to avoid this problem.
 
 Note that the operator ID (bl_idname) in this example is 'mesh.subdivide',
 'bpy.ops' is just the access path for python.
+
+
+Keywords and Positional Arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For calling operators keywords are used for operator properties and
+positional arguments are used to define how the operator is called.
+
+There are 3 optional positional arguments (documented in detail below).
+
+.. code-block:: python
+
+   bpy.ops.test.operator(override_context, execution_context, undo)
+
+* override_context - dict type
+* execution_context - string (enum)
+* undo - boolean
+
+
+Each of these arguments is optional, but must be given in the order above.
 """
 import bpy