[arrow-datafusion] branch master updated: Improve docstrings in bianry_rule.rs (#3687)

[ag...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

agrove pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion.git


The following commit(s) were added to refs/heads/master by this push:
     new df9c4189b Improve docstrings in bianry_rule.rs (#3687)
df9c4189b is described below

commit df9c4189bac84af949951d9a59960a4bf7d12521
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Mon Oct 3 19:32:22 2022 -0400

    Improve docstrings in bianry_rule.rs (#3687)
---
 datafusion/expr/src/binary_rule.rs | 39 ++++++++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 10 deletions(-)

diff --git a/datafusion/expr/src/binary_rule.rs b/datafusion/expr/src/binary_rule.rs
index 77e02cf3a..06240b615 100644
--- a/datafusion/expr/src/binary_rule.rs
+++ b/datafusion/expr/src/binary_rule.rs
@@ -74,9 +74,14 @@ pub fn binary_operator_data_type(
 /// Coercion rules for all binary operators. Returns the output type
 /// of applying `op` to an argument of `lhs_type` and `rhs_type`.
 ///
-/// TODO this function is trying to serve two purposes at once; it determines the result type
-/// of the binary operation and also determines how the inputs can be coerced but this
-/// results in inconsistencies in some cases (particular around date + interval)
+/// Returns None if no suitable type can be found.
+///
+/// TODO this function is trying to serve two purposes at once; it
+/// determines the result type of the binary operation and also
+/// determines how the inputs can be coerced but this results in
+/// inconsistencies in some cases (particular around date + interval)
+/// when the input argument types do not match the output argument
+/// types
 ///
 /// Tracking issue is https://github.com/apache/arrow-datafusion/issues/3419
 pub fn coerce_types(
@@ -146,6 +151,8 @@ pub fn coerce_types(
     }
 }
 
+/// Returns the output type of applying bitwise operations such as
+/// `&`, `|`, or `xor`to arguments of `lhs_type` and `rhs_type`.
 fn bitwise_coercion(left_type: &DataType, right_type: &DataType) -> Option<DataType> {
     use arrow::datatypes::DataType::*;
 
@@ -167,7 +174,9 @@ fn bitwise_coercion(left_type: &DataType, right_type: &DataType) -> Option<DataT
     }
 }
 
-/// Get the coerced data type for comparison operations such as `eq`, `not eq`, `lt`, `lteq`, `gt`, and `gteq`.
+/// Returns the output type of applying comparison operations such as
+/// `eq`, `not eq`, `lt`, `lteq`, `gt`, and `gteq` to arguments
+/// of `lhs_type` and `rhs_type`.
 pub fn comparison_coercion(lhs_type: &DataType, rhs_type: &DataType) -> Option<DataType> {
     if lhs_type == rhs_type {
         // same type => equality is possible
@@ -181,6 +190,9 @@ pub fn comparison_coercion(lhs_type: &DataType, rhs_type: &DataType) -> Option<D
         .or_else(|| string_numeric_coercion(lhs_type, rhs_type))
 }
 
+/// Returns the output type of applying numeric operations such as `=`
+/// to arguments `lhs_type` and `rhs_type` if one is numeric and one
+/// is `Utf8`/`LargeUtf8`.
 fn string_numeric_coercion(lhs_type: &DataType, rhs_type: &DataType) -> Option<DataType> {
     use arrow::datatypes::DataType::*;
     match (lhs_type, rhs_type) {
@@ -192,6 +204,8 @@ fn string_numeric_coercion(lhs_type: &DataType, rhs_type: &DataType) -> Option<D
     }
 }
 
+/// Returns the output type of applying numeric operations such as `=`
+/// to arguments `lhs_type` and `rhs_type` if both are numeric
 fn comparison_binary_numeric_coercion(
     lhs_type: &DataType,
     rhs_type: &DataType,
@@ -207,7 +221,7 @@ fn comparison_binary_numeric_coercion(
     }
 
     // these are ordered from most informative to least informative so
-    // that the coercion removes the least amount of information
+    // that the coercion does not lose information via truncation
     match (lhs_type, rhs_type) {
         // support decimal data type for comparison operation
         (d1 @ Decimal128(_, _), d2 @ Decimal128(_, _)) => get_wider_decimal_type(d1, d2),
@@ -227,6 +241,8 @@ fn comparison_binary_numeric_coercion(
     }
 }
 
+/// Returns the output type of applying numeric operations such as `=`
+/// to a decimal type `decimal_type` and `other_type`
 fn get_comparison_common_decimal_type(
     decimal_type: &DataType,
     other_type: &DataType,
@@ -252,9 +268,10 @@ fn get_comparison_common_decimal_type(
     }
 }
 
-// Returns a `DataType::Decimal128` that can store any value from either
-// `lhs_decimal_type` and `rhs_decimal_type`
-// The result decimal type is (max(s1, s2) + max(p1-s1, p2-s2), max(s1, s2)).
+/// Returns a `DataType::Decimal128` that can store any value from either
+/// `lhs_decimal_type` and `rhs_decimal_type`
+///
+/// The result decimal type is `(max(s1, s2) + max(p1-s1, p2-s2), max(s1, s2))`.
 fn get_wider_decimal_type(
     lhs_decimal_type: &DataType,
     rhs_type: &DataType,
@@ -270,8 +287,8 @@ fn get_wider_decimal_type(
     }
 }
 
-// Convert the numeric data type to the decimal data type.
-// Now, we just support the signed integer type and floating-point type.
+/// Convert the numeric data type to the decimal data type.
+/// Now, we just support the signed integer type and floating-point type.
 fn coerce_numeric_type_to_decimal(numeric_type: &DataType) -> Option<DataType> {
     match numeric_type {
         DataType::Int8 => Some(DataType::Decimal128(3, 0)),
@@ -285,6 +302,8 @@ fn coerce_numeric_type_to_decimal(numeric_type: &DataType) -> Option<DataType> {
     }
 }
 
+/// Returns the output type of applying mathematics operations such as
+/// `+` to arguments of `lhs_type` and `rhs_type`.
 fn mathematics_numerical_coercion(
     mathematics_op: &Operator,
     lhs_type: &DataType,