[FIX] doc: API of create

doc/reference/orm.rst

@@ -278,12 +278,18 @@ Common ORM methods
    .. tip:: to just check if any record matches a domain, or count the number
              of records which do, use
              :meth:`~odoo.models.Model.search_count`
-:meth:`~odoo.models.Model.create`
-    Takes a number of field values, and returns a recordset containing the
-    record created::
 
-        >>> self.create({'name': "New Name"})
+:meth:`~odoo.models.Model.create`
+    Takes a dictionary of field values, or a list of such dictionaries, and
+    returns a recordset containing the records created::
+
+        >>> self.create({'name': "Joe"})
         res.partner(78)
+        >>> self.create([{'name': "Jack"}, {'name': "William"}, {'name': "Averell"}])
+        res.partner(79, 80, 81)
+
+    See :ref:`how to define method `create` with one API or the other
+    <reference/orm/oldapi>`.
 
 :meth:`~odoo.models.Model.write`
     Takes a number of field values, writes them to all the records in its
@@ -569,6 +575,19 @@ Two decorators can expose a new-style method to the old API:
         # can be called as
         old_style_model.some_method(cr, uid, [id1, id2], a_value, context=context)
 
+Note that a method `create` decorated with :func:`~odoo.api.model` will always
+be called with a single dictionary. A method `create` decorated with the variant
+:func:`~odoo.api.model_create_multi` will always be called with a list of dicts.
+The decorators take care of converting the argument to one form or the other::
+
+    @api.model
+    def create(self, vals):
+        ...
+
+    @api.model_create_multi
+    def create(self, vals_list):
+        ...
+
 Because new-style APIs tend to return recordsets and old-style APIs tend to
 return lists of ids, there is also a decorator managing this: