[DOC] orm: documented workflow-related methods.

bzr revid: vmt@openerp.com-20130206150244-hs67hhe35okl42ei

doc/index.rst

@@ -34,6 +34,7 @@ OpenERP Server API
 .. toctree::
    :maxdepth: 1
 
+   orm-methods.rst
    api_models.rst
 
 Concepts

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).

doc/workflows.rst

@@ -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()

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)