From f27707e6032790be2115321a76bec44cbeb4d8c9 Mon Sep 17 00:00:00 2001
From: BharatDeva <278575558+BharatDeva@users.noreply.github.com>
Date: Tue, 5 May 2026 19:16:21 -0500
Subject: [PATCH] docs: document null-handling function arguments

---
 python/datafusion/functions.py | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/python/datafusion/functions.py b/python/datafusion/functions.py
index 08062851a..4e01bfb93 100644
--- a/python/datafusion/functions.py
+++ b/python/datafusion/functions.py
@@ -908,6 +908,9 @@ def chr(arg: Expr) -> Expr:
 def coalesce(*args: Expr) -> Expr:
     """Returns the value of the first expr in ``args`` which is not NULL.
 
+    Args:
+        *args: Expressions to evaluate in order.
+
     Examples:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [None, 1], "b": [2, 3]})
@@ -1089,6 +1092,10 @@ def greatest(*args: Expr) -> Expr:
 def ifnull(x: Expr, y: Expr) -> Expr:
     """Returns ``x`` if ``x`` is not NULL. Otherwise returns ``y``.
 
+    Args:
+        x: Expression to return when it is not NULL.
+        y: Fallback expression to return when ``x`` is NULL.
+
     See Also:
         This is an alias for :py:func:`nvl`.
     """
@@ -1323,6 +1330,10 @@ def md5(arg: Expr) -> Expr:
 def nanvl(x: Expr, y: Expr) -> Expr:
     """Returns ``x`` if ``x`` is not ``NaN``. Otherwise returns ``y``.
 
+    Args:
+        x: Expression to return when it is not NaN.
+        y: Fallback expression to return when ``x`` is NaN.
+
     Examples:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [np.nan, 1.0], "b": [0.0, 0.0]})
@@ -1339,6 +1350,10 @@ def nanvl(x: Expr, y: Expr) -> Expr:
 def nvl(x: Expr, y: Expr) -> Expr:
     """Returns ``x`` if ``x`` is not ``NULL``. Otherwise returns ``y``.
 
+    Args:
+        x: Expression to return when it is not NULL.
+        y: Fallback expression to return when ``x`` is NULL.
+
     Examples:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [None, 1], "b": [0, 0]})
@@ -1356,6 +1371,11 @@ def nvl(x: Expr, y: Expr) -> Expr:
 def nvl2(x: Expr, y: Expr, z: Expr) -> Expr:
     """Returns ``y`` if ``x`` is not NULL. Otherwise returns ``z``.
 
+    Args:
+        x: Expression to check for NULL.
+        y: Expression to return when ``x`` is not NULL.
+        z: Expression to return when ``x`` is NULL.
+
     Examples:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [None, 1], "b": [10, 20], "c": [30, 40]})