From 6b459a1f279bc9568737ad75ac274facf76f29d4 Mon Sep 17 00:00:00 2001
From: Vo Minh Thu <vmt@openerp.com>
Date: Wed, 6 Feb 2013 16:02:44 +0100
Subject: [PATCH] [DOC] orm: documented workflow-related methods.

bzr revid: vmt@openerp.com-20130206150244-hs67hhe35okl42ei
---
 doc/index.rst       |  1 +
 doc/orm-methods.rst | 51 +++++++++++++++++++++++++++++++++++++++++++++
 doc/workflows.rst   | 13 ------------
 openerp/osv/orm.py  |  7 +++++++
 4 files changed, 59 insertions(+), 13 deletions(-)
 create mode 100644 doc/orm-methods.rst
 delete mode 100644 doc/workflows.rst

diff --git a/doc/index.rst b/doc/index.rst
index 33474e2da57..0040394a789 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -34,6 +34,7 @@ OpenERP Server API
 .. toctree::
    :maxdepth: 1
 
+   orm-methods.rst
    api_models.rst
 
 Concepts
diff --git a/doc/orm-methods.rst b/doc/orm-methods.rst
new file mode 100644
index 00000000000..6085a12c50b
--- /dev/null
+++ b/doc/orm-methods.rst
@@ -0,0 +1,51 @@
+.. _orm-methods:
+
+ORM methods
+===========
+
+.. _orm-workflows:
+
+Workflow-related methods
+------------------------
+
+.. versionadded:: 7.1
+
+Creating, deleting, or otherwise manipulating workflow instances is possible
+right from a Model instance. (Previously, workflows were handled throught a
+call to ``LocalService('workflow')``. Using the ORM methods is now the preferred
+way.)
+
+.. currentmodule:: openerp.osv.orm
+
+.. automethod:: BaseModel.create_workflow
+  :noindex:
+
+  This is used instead of ``LocalService('workflow').trg_create()``.
+
+.. automethod:: BaseModel.delete_workflow
+  :noindex:
+
+  This is used instead of ``LocalService('workflow').trg_delete()``.
+
+.. automethod:: BaseModel.redirect_workflow
+  :noindex:
+
+.. method:: BaseModel.signal_xxx(cr, uid, ids)
+  :noindex:
+
+  Sends a signal ``xxx`` to the workflow instances bound to the given record
+  IDs. (This is implemented using ``__getattr__`` so no source link is
+  rendered on the right.)
+
+  This is used instead of ``LocalService('workflow').trg_validate()``.
+
+
+.. note::
+  Low-level access to the workflows is still possible by using the
+  ``openerp.workflow`` module, that is, in a similar way to what was possible
+  with the previous ``LocalService('workflow')`` access. This may be useful
+  when looking-up a model in the registry and/or its records is not necessary.
+  For instance when working with raw model names and record IDs is preferred (to
+  avoid hitting unnecessarily the database). But this is something that should be
+  carefully considered as it would bypass the ORM methods (and thus any inherited
+  behaviors).
diff --git a/doc/workflows.rst b/doc/workflows.rst
deleted file mode 100644
index 61a58575c9b..00000000000
--- a/doc/workflows.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. _workflows:
-
-Workflows
-=========
-
-- Low-level workflow functions (i.e. the openerp.workflow "service").
-  Useful when looking-up a model and its records is not necessary, i.e. when
-  working with raw model name and record ids is preferred (less hit to the
-  database). Cannot really be used as it would bypass the ORM methods.
-- Model-level (ORM) methods.
-- XML-RPC endpoint and methods.
-
-- Blah Model.signal_xxxx()
diff --git a/openerp/osv/orm.py b/openerp/osv/orm.py
index 64b44d9e743..5255792800e 100644
--- a/openerp/osv/orm.py
+++ b/openerp/osv/orm.py
@@ -3929,18 +3929,25 @@ class BaseModel(object):
         return result
 
     def create_workflow(self, cr, uid, ids):
+        """Create a workflow instance for each given record IDs."""
         wf_service = netsvc.LocalService("workflow")
         for res_id in ids:
             wf_service.trg_create(uid, self._name, res_id, cr)
         return True
 
     def delete_workflow(self, cr, uid, ids):
+        """Delete the workflow instances bound to the given record IDs."""
         wf_service = netsvc.LocalService("workflow")
         for res_id in ids:
             wf_service.trg_create(uid, self._name, res_id, cr)
         return True
 
     def redirect_workflow(self, cr, uid, old_new_ids):
+        """
+        Rebind the workflow instance bound to the given 'old' record IDs to
+        the given 'new' IDs. (``old_new_ids`` is a list of pairs
+        ``(old, new)``.
+        """
         wf_service = netsvc.LocalService("workflow")
         for old_id, new_id in old_new_ids:
             wf_service.trg_redirect(uid, self._name, old_id, new_id, cr)