[IMP] developer/reference: new usage of Model.mapped()

odoo/odoo#185630

content/developer/reference/backend/orm.rst

@@ -1086,13 +1086,17 @@ Map
 
 .. note::
 
-    Since V13, multi-relational field access is supported and works like a mapped call:
+    Accessing relational attributes returns the union of the recordsets.
+    You should probably always use simple attribute access and only ``mapped``
+    when you may have multiple records and you want to get a value for each
+    record in the recordset.
 
     .. code-block:: python3
 
-        records.partner_id  # == records.mapped('partner_id')
-        records.partner_id.bank_ids  # == records.mapped('partner_id.bank_ids')
-        records.partner_id.mapped('name')  # == records.mapped('partner_id.name')
+        records.partner_id  # union of partner_id from records
+        records.mapped('partner_id')  # [record['partner_id'] for record in records]
+        records.partner_id.bank_ids  # union of banks of partners of records
+        records.mapped('partner_id.name')  # for each record, get the name of the partner
 
 Sort
 ~~~~

content/developer/reference/backend/orm/changelog.rst

@@ -10,6 +10,8 @@ Odoo Online version 18.1
 - Declare constraints and indexes as model attributes with `#175783 <https://github.com/odoo/odoo/pull/175783>`_.
 - The `json` controllers have been renamed to `jsonrpc`. They are called the same, only the
   `type` in the python files changed. See `#183636 <https://github.com/odoo/odoo/pull/183636>`_.
+- Models' `mapped` function now behaves more like the `map` function: it always returns a
+  list where each element of the recordset is mapped. See `#185630 <https://github.com/odoo/odoo/pull/185630>`_.
 
 Odoo version 18.0
 =================

content/developer/tutorials/pdf_reports.rst

@@ -124,7 +124,7 @@ our minimal property offers template file:
                                     </tr>
                                 </thead>
                                 <tbody>
-                                    <t t-set="offers" t-value="property.mapped('offer_ids')"/>
+                                    <t t-set="offers" t-value="property.offer_ids"/>
                                     <tr t-foreach="offers" t-as="offer">
                                         <td>
                                             <span t-field="offer.price"/>