From 18314cf645aaa0a817526638cc4e487fcf6f8de5 Mon Sep 17 00:00:00 2001
From: Raphael Collet <rco@openerp.com>
Date: Mon, 4 Aug 2014 09:49:35 +0200
Subject: [PATCH] [IMP] openerp.api: improve documentation

---
 openerp/api.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/openerp/api.py b/openerp/api.py
index 6c70910633f..725d301ffd4 100644
--- a/openerp/api.py
+++ b/openerp/api.py
@@ -273,8 +273,8 @@ def get_context_split(method):
 
 
 def model(method):
-    """ Decorate a record-style method where `self` is a recordset. Such a
-        method::
+    """ Decorate a record-style method where `self` is a recordset, but its
+        contents is not relevant, only the model is. Such a method::
 
             @api.model
             def method(self, args):
@@ -286,6 +286,8 @@ def model(method):
             recs.method(args)
 
             model.method(cr, uid, args, context=context)
+
+        Notice that no `ids` are passed to the method in the traditional style.
     """
     method._api = model
     split = get_context_split(method)
@@ -301,8 +303,8 @@ def model(method):
 
 
 def multi(method):
-    """ Decorate a record-style method where `self` is a recordset. Such a
-        method::
+    """ Decorate a record-style method where `self` is a recordset. The method
+        typically defines an operation on records. Such a method::
 
             @api.multi
             def method(self, args):