From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 3 Oct 2022 15:40:27 +0000 (-0400)
Subject: clarify precedence docs
X-Git-Tag: rel_1_4_42~14
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f35446512582defc2fcde826b8c059ed09ddabf3;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

clarify precedence docs

Change-Id: I748f2736eb6382c8625b3419a82785b48766d8f7
references: #8584
(cherry picked from commit b295a3b58f13d566c37244448218e4287f5e47ee)
---

diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index 1da5032296..806d41eaf8 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -145,13 +145,20 @@ class Operators(object):
           between this element and the expression passed to the
           generated function.
 
-        :param precedence: precedence to apply to the operator, when
-         parenthesizing expressions.  A lower number will cause the expression
-         to be parenthesized when applied against another operator with
-         higher precedence.  The default value of ``0`` is lower than all
-         operators except for the comma (``,``) and ``AS`` operators.
-         A value of 100 will be higher or equal to all operators, and -100
-         will be lower than or equal to all operators.
+        :param precedence: precedence which the database is expected to apply
+         to the operator in SQL expressions. This integer value acts as a hint
+         for the SQL compiler to know when explicit parenthesis should be
+         rendered around a particular operation. A lower number will cause the
+         expression to be parenthesized when applied against another operator
+         with higher precedence. The default value of ``0`` is lower than all
+         operators except for the comma (``,``) and ``AS`` operators. A value
+         of 100 will be higher or equal to all operators, and -100 will be
+         lower than or equal to all operators.
+
+         .. seealso::
+
+            :ref:`faq_sql_expression_op_parenthesis` - detailed description
+            of how the SQLAlchemy SQL compiler renders parenthesis
 
         :param is_comparison: legacy; if True, the operator will be considered
          as a "comparison" operator, that is which evaluates to a boolean