Move unionall_type to Utilities, add docs (#2238)

This PR moves the two identical instances of `unionall_type` (and the
similarly named `union_all_type`) to a common function in `Utilities`.
It also adds examples to clarify what the function does.

Author: Sbozzolo

src/DataLayouts/DataLayouts.jl

@@ -69,6 +69,7 @@ import ClimaComms
 import MultiBroadcastFusion as MBF
 import Adapt
 
+import ..Utilities: PlusHalf, unionall_type
 import ..DebugOnly: call_post_op_callback, post_op_callback
 import ..slab, ..slab_args, ..column, ..column_args, ..level
 export slab,
@@ -2335,10 +2336,8 @@ function ColumnMask(
     return IJHMask(is_active)
 end
 
-union_all_type(::Type{T}) where {T} = T.name.wrapper
-
 function IJHMask(is_active::Union{IJFH, IJHF})
-    DA = union_all_type(typeof(parent(is_active)))
+    DA = unionall_type(typeof(parent(is_active)))
     (Ni, Nj, _, _, Nh) = size(is_active)
     Nijh = Ni * Nj * Nh
     i_map = zeros(Int, Nijh)

src/Operators/finitedifference.jl

@@ -1,4 +1,4 @@
-import ..Utilities: PlusHalf, half
+import ..Utilities: PlusHalf, half, unionall_type
 import UnrolledUtilities: unrolled_map
 
 const AllFiniteDifferenceSpace =
@@ -3296,13 +3296,6 @@ Base.@propagate_inbounds function stencil_right_boundary(
     stencil_interior(op, loc, space, idx - 1, hidx, arg)
 end
 
-"""
-    unionall_type(::Type{T})
-
-Extract the type of the input, and strip it of any type parameters.
-"""
-unionall_type(::Type{T}) where {T} = T.name.wrapper
-
 # Extend `adapt_structure` for all boundary conditions containing a `val` field.
 function Adapt.adapt_structure(to, bc::AbstractBoundaryCondition)
     if hasfield(typeof(bc), :val)

src/Utilities/Utilities.jl

@@ -30,4 +30,35 @@ Base.@propagate_inbounds linear_ind(n::NTuple, ci::CartesianIndex) =
 Base.@propagate_inbounds linear_ind(n::NTuple, loc::NTuple) =
     linear_ind(n, CartesianIndex(loc))
 
+"""
+    unionall_type(::Type{T})
+
+Extract the type of the input, and strip it of any type parameters.
+
+This is useful when one needs the generic constructor for a given type.
+
+Example
+=======
+```julia
+julia> unionall_type(typeof([1, 2, 3]))
+Array
+
+julia> struct Foo{A, B}
+               a::A
+               b::B
+       end
+
+julia> unionall_type(typeof(Foo(1,2)))
+Foo
+```
+"""
+function unionall_type(::Type{T}) where {T}
+    # NOTE: As of version 1.12, there is no simple, user-friendly way to extract
+    # the generic type of T, so we need to reach for the internals in Julia.
+    # Hopefully, Julia will introduce a simpler, more stable way to do this in a
+    # future release.
+    return T.name.wrapper
+end
+
+
 end # module