fix|test|doc: Correct by-key reduction output dtypes, expand tests and docs

Fix countByKey/allTrueByKey/anyTrueByKey return types to reflect the
actual ArrayFire output dtype (Word32/CBool) rather than the input value
type, preventing host over-reads on toList. Add property tests for
by-key reductions, vector round-trips, and bitNot involution/complement.
Document the FFI marshalling combinators, Eq/Num Array instances, and
several API functions.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dmjio

src/ArrayFire/Algorithm.hs

@@ -757,6 +757,8 @@ maxByKey keys vals (fromIntegral -> dim) =
   op2p2kv keys vals (\ko vo k v -> af_max_by_key ko vo k v dim)
 
 -- | True if all values are true within each key group.
+--
+-- The value output is always boolean (@b8@) regardless of the input value type.
 allTrueByKey
   :: AFType a
   => Array Int
@@ -765,11 +767,13 @@ allTrueByKey
   -- ^ Values array (treated as boolean)
   -> Int
   -- ^ Dimension
-  -> (Array Int, Array a)
+  -> (Array Int, Array CBool)
 allTrueByKey keys vals (fromIntegral -> dim) =
   op2p2kv keys vals (\ko vo k v -> af_all_true_by_key ko vo k v dim)
 
 -- | True if any value is true within each key group.
+--
+-- The value output is always boolean (@b8@) regardless of the input value type.
 anyTrueByKey
   :: AFType a
   => Array Int
@@ -778,11 +782,13 @@ anyTrueByKey
   -- ^ Values array (treated as boolean)
   -> Int
   -- ^ Dimension
-  -> (Array Int, Array a)
+  -> (Array Int, Array CBool)
 anyTrueByKey keys vals (fromIntegral -> dim) =
   op2p2kv keys vals (\ko vo k v -> af_any_true_by_key ko vo k v dim)
 
 -- | Count non-zero values within each key group.
+--
+-- The value output is always @u32@ regardless of the input value type.
 countByKey
   :: AFType a
   => Array Int
@@ -791,6 +797,6 @@ countByKey
   -- ^ Values array
   -> Int
   -- ^ Dimension
-  -> (Array Int, Array a)
+  -> (Array Int, Array Word32)
 countByKey keys vals (fromIntegral -> dim) =
   op2p2kv keys vals (\ko vo k v -> af_count_by_key ko vo k v dim)

src/ArrayFire/Arith.hs

@@ -1299,7 +1299,8 @@ atan2Batched x y (fromIntegral . fromEnum -> batch) = do
   x `op2` y $ \arr arr1 arr2 ->
     af_atan2 arr arr1 arr2 batch
 
--- | Take the cplx2 of all values in an 'Array'
+-- | Construct a complex 'Array' from two real 'Array's, taking the first as the
+-- real part and the second as the imaginary part.
 --
 -- >>> A.cplx2 (A.vector @Int 10 [1..]) (A.vector @Int 10 [1..])
 -- ArrayFire Array
@@ -1321,12 +1322,13 @@ cplx2
   -> Array a
   -- ^ Second input (imaginary part)
   -> Array (Complex a)
-  -- ^ Result of cplx2
+  -- ^ Complex result with the inputs as real and imaginary parts
 cplx2 x y =
   x `op2` y $ \arr arr1 arr2 ->
     af_cplx2 arr arr1 arr2 1
 
--- | Take the cplx2Batched of all values in an 'Array'
+-- | Construct a complex 'Array' from two real 'Array's (real and imaginary
+-- parts), with explicit control over batched broadcasting of the inputs.
 --
 -- >>> A.cplx2Batched (A.vector @Int 10 [1..]) (A.vector @Int 10 [1..]) True
 -- ArrayFire Array
@@ -1348,9 +1350,9 @@ cplx2Batched
   -> Array a
   -- ^ Second input (imaginary part)
   -> Bool
-  -- ^ Use batch
+  -- ^ Whether to enable batched broadcasting of the inputs
   -> Array (Complex a)
-  -- ^ Result of cplx2
+  -- ^ Complex result with the inputs as real and imaginary parts
 cplx2Batched x y (fromIntegral . fromEnum -> batch) = do
   x `op2` y $ \arr arr1 arr2 ->
     af_cplx2 arr arr1 arr2 batch

src/ArrayFire/Array.hs

@@ -211,7 +211,9 @@ mkArray dims xs =
 
 -- | Constructs an 'Array' from a 'Storable' 'Vector', avoiding the intermediate list allocation of 'mkArray'.
 --
--- The vector's pinned buffer is passed directly to @af_create_array@.
+-- The vector's contiguous buffer is handed straight to @af_create_array@, which
+-- copies it into the 'Array' (and uploads to device memory on GPU backends), so
+-- no intermediate Haskell list is built.
 -- Throws 'AFException' if the vector length does not match the product of the given dimensions.
 --
 -- >>> fromVector @Double [3] (Data.Vector.Storable.fromList [1,2,3])

src/ArrayFire/Data.hs

@@ -396,6 +396,10 @@ joinMany (fromIntegral -> n) (fmap (\(Array fp) -> fp) -> arrays) = unsafePerfor
   Array <$>
     newForeignPtr af_release_array_finalizer newPtr
 
+-- | Marshals a list of 'ForeignPtr' into a temporary, contiguous C array of
+-- raw pointers, keeping every 'ForeignPtr' alive for the duration of the
+-- action. The continuation receives the number of pointers and a pointer to
+-- the array.
 withManyForeignPtr :: [ForeignPtr a] -> (Int -> Ptr (Ptr a) -> IO b) -> IO b
 withManyForeignPtr fptrs action = go [] fptrs
   where