[FIX] util/fields: fix documenation

* Correct references to `adapt_domains`
* Explain domain adapters better
* Typos and wording improvements

closes #89

Signed-off-by: Christophe Simonis (chs) <[email protected]>

Author: aj-fuentes

src/util/domains.py

@@ -307,7 +307,7 @@ def clean_term(term):
 
 def adapt_domains(cr, model, old, new, adapter=None, skip_inherit=(), force_adapt=False):
     """
-    Replace `old` by `new` in all domains of `model` and all its inheriting models using an `adapter` callback.
+    Replace `old` by `new` in domains using `model` and inheriting models.
 
     `adapter` is a callback function to adapt leaves. Adapter functions must take three
     arguments and return a `domain <reference/orm/domains>`_ that substitutes the original
@@ -330,12 +330,16 @@ def adapter(leaf, in_or, negated):
                     return [(left, "=", ko)]
                 return [leaf]
 
-    `adapter` is called only on leafs that use the `old` field of `model` as **last** part
-    of the `left` part of leaves, unless `force_adapt` is `True`. The domains returned by
-    an adapter do not need to have the `old` field replaced by `new` in the `left` part of
-    the input leaf. The replace will be done anyway to the whole domain returned by the
-    adapter. The purpose of the `adapter` is to modify the operator and the `right` part
-    of the input leaf.
+    `adapter` is called only on leaves that use the `old` field of `model` as **last**
+    part of the `left` part of leaves, unless `force_adapt` is `True`. In the latter case
+    the adapter is called if the field appears anywhere in the path, useful for relational
+    fields only.
+
+    The domains returned by an adapter do not need to have the `old` field replaced by
+    `new` in the `left` part of the input leaf. The replace will be done anyway to the
+    whole domain returned by the adapter. The usual purpose of the `adapter` is to modify
+    the operator and the `right` part of the input leaf. When `adapter` is not set only
+    the replacement takes place.
 
     .. example::
        When replacing `"field1"` by `"field2"`, the following happens:
@@ -355,9 +359,9 @@ def adapter(leaf, in_or, negated):
     :param str new: name of the field that should replace `old`
     :param function adapter: adapter for leaves
     :param list(str) skip_inherit: list of inheriting model names to don't adapt (skip)
-    :param bool force_adapt: when `True, run the `adapter` on all leaves having `new` in
-                                   `left` part of the leaf (path), useful when deleting a
-                                   field (in which case `new` is ignored).
+    :param bool force_adapt: when `True`, run the `adapter` on all leaves having `new` in
+                             `left` part of the leaf (path), useful when deleting a field
+                             (in which case `new` is ignored).
     """
     _validate_model(model)
     target_model = model

src/util/fields.py

@@ -430,21 +430,25 @@ def move_field_to_module(cr, model, fieldname, old_module, new_module, skip_inhe
 
 def rename_field(cr, model, old, new, update_references=True, domain_adapter=None, skip_inherit=()):
     """
-    Rename a field and its references from `old` to `new` on the given `model` and all inheriting models, unless exceptions are specified in `skip_inherit`.
+    Rename a field and its references from `old` to `new` on the given `model`.
+
+    The field is updated in all inheriting models, except for models specified in
+    `skip_inherit`.
 
     This functions also updates references, indirect or direct ones, including filters,
     server actions, related fields, emails, dashboards, domains, and many more. See
-    :func:`update_field_usage`
+    :func:`~odoo.upgrade.util.fields.update_field_usage`
 
     For the update of domains a special adapter function can be used. The default adapter
-    just replaces `old` by `new` in each domain leaf. Refer to :func:`adapt_domains` for
-    information about domain adapters.
+    just replaces `old` by `new` in each domain leaf. Refer to
+    :func:`~odoo.upgrade.util.domains.adapt_domains` for information about domain adapters.
 
     :param str model: model name of the field to rename
     :param str old: current name of the field to rename
     :param str new: new name of the field to rename
     :param bool update_references: whether to update all references
-    :param function domain_adapter: adapter to use for domains, see :func:`adapt_domains`
+    :param function domain_adapter: adapter to use for domains, see
+                                    :func:`~odoo.upgrade.util.domains.adapt_domains`
     :param list(str) or str skip_inherit: models to skip when renaming the field in
                                           inheriting models, use `"*"` to skip all
     """
@@ -932,13 +936,14 @@ def update_field_usage(cr, model, old, new, domain_adapter=None, skip_inherit=()
 
     This function can be used to replace the usage of a field by another. Domains are
     updated using the `domain_adapter`. By default the domain adapter just replaces `old`
-    by `new` in domain leaves. See :func:`adapt_domains` for more information about domain
-    adapters.
+    by `new` in domain leaves. See :func:`~odoo.upgrade.util.domains.adapt_domains` for
+    more information about domain adapters.
 
     :param str model: model name of the field
     :param str old: source name of the field to replace
     :param str new: target name of the field to set
-    :param function domain_adapter: adapter to use for domains, see :func:`adapt_domains`
+    :param function domain_adapter: adapter to use for domains, see
+                                    :func:`~odoo.upgrade.util.domains.adapt_domains`
     :param list(str) or str skip_inherit: models to skip when renaming the field in
                                           inheriting models, use `"*"` to skip all
     """