From be19a9e9aa547b924e6db284bbac72affd6e6ecf Mon Sep 17 00:00:00 2001
From: Adrian Torres <adt@odoo.com>
Date: Thu, 1 Apr 2021 13:59:45 +0000
Subject: [PATCH] [DOC] orm: document Query._join method

From having to work with it recently, it was not super clear what each
argument did (especially the link argument), and more documentation =
more betterer code
---
 odoo/osv/query.py | 47 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/odoo/osv/query.py b/odoo/osv/query.py
index a6d414d2d29..8e96c4ea905 100644
--- a/odoo/osv/query.py
+++ b/odoo/osv/query.py
@@ -86,14 +86,57 @@ class Query(object):
         self._where_params.extend(where_params)
 
     def join(self, lhs_alias, lhs_column, rhs_table, rhs_column, link, extra=None, extra_params=()):
-        """ Add an INNER JOIN to the current table (if necessary), and return
-        the alias corresponding to ``rhs_table``.
+        """
+        Perform a join between a table already present in the current Query object and
+        another table.
+
+        :param str lhs_alias: alias of a table already defined in the current Query object.
+        :param str lhs_column: column of `lhs_alias` to be used for the join's ON condition.
+        :param str rhs_table: name of the table to join to `lhs_alias`.
+        :param str rhs_column: column of `rhs_alias` to be used for the join's ON condition.
+        :param str link: used to generate the alias for the joined table, this string should
+            represent the relationship (the link) between both tables.
+        :param str extra: an sql string of a predicate or series of predicates to append to the
+            join's ON condition, `lhs_alias` and `rhs_alias` can be injected if the string uses
+            the `lhs` and `rhs` variables with the `str.format` syntax. e.g.::
+
+                query.join(..., extra="{lhs}.name != {rhs}.name OR ...", ...)
+
+        :param tuple extra_params: a tuple of values to be interpolated into `extra`, this is
+            done by psycopg2.
+
+        Full example:
+
+        >>> rhs_alias = query.join(
+        ...     "res_users",
+        ...     "partner_id",
+        ...     "res_partner",
+        ...     "id",
+        ...     "partner_id",           # partner_id is the "link" from res_users to res_partner
+        ...     "{lhs}.\"name\" != %s",
+        ...     ("Mitchell Admin",),
+        ... )
+        >>> rhs_alias
+        res_users_res_partner__partner_id
+
+        From the example above, the resulting query would be something like::
+
+            SELECT ...
+            FROM "res_users" AS "res_users"
+            JOIN "res_partner" AS "res_users_res_partner__partner_id"
+                ON "res_users"."partner_id" = "res_users_res_partner__partner_id"."id"
+                AND "res_users"."name" != 'Mitchell Admin'
+            WHERE ...
+
         """
         return self._join('JOIN', lhs_alias, lhs_column, rhs_table, rhs_column, link, extra, extra_params)
 
     def left_join(self, lhs_alias, lhs_column, rhs_table, rhs_column, link, extra=None, extra_params=()):
         """ Add a LEFT JOIN to the current table (if necessary), and return the
         alias corresponding to ``rhs_table``.
+
+        See the documentation of :meth:`~odoo.osv.query.Query.join` for a better overview of the
+        arguments and what they do.
         """
         return self._join('LEFT JOIN', lhs_alias, lhs_column, rhs_table, rhs_column, link, extra, extra_params)