DOC: Add note on inference behavior of apply with result_type='expand'

Author: pinkgradient

pandas/core/frame.py

@@ -10378,6 +10378,7 @@ def apply(
         ----------
         func : function
             Function to apply to each column or row.
+        
         axis : {0 or 'index', 1 or 'columns'}, default 0
             Axis along which the function is applied:
 
@@ -10396,18 +10397,25 @@ def apply(
 
         result_type : {'expand', 'reduce', 'broadcast', None}, default None
             These only act when ``axis=1`` (columns):
-
+        
             * 'expand' : list-like results will be turned into columns.
+              Note: The output type is inferred from the first function return value.
+              If the first return value is not list-like (e.g., None or NaN), expansion
+              will not occur, and the result may be a Series instead of a DataFrame.
+              To avoid inconsistent output types, ensure your function returns consistent
+              list-like objects (e.g., an empty dict {}) for missing or NaN-like values.
+        
             * 'reduce' : returns a Series if possible rather than expanding
               list-like results. This is the opposite of 'expand'.
             * 'broadcast' : results will be broadcast to the original shape
               of the DataFrame, the original index and columns will be
               retained.
-
+        
             The default behaviour (None) depends on the return value of the
             applied function: list-like results will be returned as a Series
             of those. However if the apply function returns a Series these
-            are expanded to columns.
+            are expanded to columns.            
+        
         args : tuple
             Positional arguments to pass to `func` in addition to the
             array/series.