From 83a5bc53fbf7e61f05a00922d1c3c503d2b6b3db Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Thu, 28 Apr 2022 14:35:00 -0400
Subject: [PATCH] Clarify docs on UnionBuilder::append_null

---
 arrow/src/array/builder.rs | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/arrow/src/array/builder.rs b/arrow/src/array/builder.rs
index 1c64b5062b94..cece334f61a4 100644
--- a/arrow/src/array/builder.rs
+++ b/arrow/src/array/builder.rs
@@ -2064,7 +2064,13 @@ impl UnionBuilder {
         }
     }
 
-    /// Appends a null to this builder.
+    /// Appends a null to this builder, encoding the null in the array
+    /// of the `type_name` child / field.
+    ///
+    /// Since `UnionArray` encodes nulls as an entry in its children
+    /// (it doesn't have a validity bitmap itself), and where the null
+    /// is part of the final array, appending a NULL requires
+    /// specifying which field (child) to use.
     #[inline]
     pub fn append_null<T: ArrowPrimitiveType>(&mut self, type_name: &str) -> Result<()> {
         self.append_option::<T>(type_name, None)