From af0c099079dae7aa52a660b883204035cbed99c3 Mon Sep 17 00:00:00 2001
From: Tom Smeding <tom@tomsmeding.com>
Date: Tue, 2 Dec 2025 15:02:19 +0100
Subject: Doc comments

---
 src/Data/Array/Nested/Mixed.hs  | 13 ++++++-------
 src/Data/Array/Nested/Ranked.hs |  3 ++-
 2 files changed, 8 insertions(+), 8 deletions(-)

(limited to 'src/Data')

diff --git a/src/Data/Array/Nested/Mixed.hs b/src/Data/Array/Nested/Mixed.hs
index d658ed3..182943d 100644
--- a/src/Data/Array/Nested/Mixed.hs
+++ b/src/Data/Array/Nested/Mixed.hs
@@ -728,6 +728,8 @@ msize = shxSize . mshape
 -- the entire hierarchy (after distributing out tuples) must be a rectangular
 -- array. The type of 'mgenerate' allows this requirement to be broken very
 -- easily, hence the runtime check.
+--
+-- If your element type @a@ is a scalar, use the faster 'mgeneratePrim'.
 mgenerate :: forall sh a. KnownElt a => IShX sh -> (IIxX sh -> a) -> Mixed sh a
 mgenerate sh f = case shxEnum sh of
   [] -> memptyArrayUnsafe sh
@@ -739,9 +741,6 @@ mgenerate sh f = case shxEnum sh of
          else runST $ do
                 vecs <- mvecsUnsafeNew sh firstelem
                 mvecsWrite sh firstidx firstelem vecs
-                -- This is likely fine if @a@ is big, but if @a@ is a scalar
-                -- this array copying is inefficient so it's better to use
-                -- the @mgeneratePrim@ below.
                 forM_ restidxs $ \idx -> do
                   let val = f idx
                   when (not (mshapeTreeEq (Proxy @a) (mshapeTree val) shapetree)) $
@@ -749,10 +748,10 @@ mgenerate sh f = case shxEnum sh of
                   mvecsWrite sh idx val vecs
                 mvecsFreeze sh vecs
 
--- | An optimized special case of `mgenerate', where the function results
--- are of a primitive type and so there's not need to verify the shapes
--- of them all are equal. This is also generalized to aribitrary @Num@ index
--- type compared to @mgenerate@.
+-- | An optimized special case of 'mgenerate', where the function results
+-- are of a primitive type and so there's not need to check that all shapes
+-- are equal. This is also generalized to an arbitrary @Num@ index type
+-- compared to @mgenerate@.
 {-# INLINE mgeneratePrim #-}
 mgeneratePrim :: forall sh a i. (PrimElt a, Num i)
               => IShX sh -> (IxX sh i -> a) -> Mixed sh a
diff --git a/src/Data/Array/Nested/Ranked.hs b/src/Data/Array/Nested/Ranked.hs
index 37925fb..b77b529 100644
--- a/src/Data/Array/Nested/Ranked.hs
+++ b/src/Data/Array/Nested/Ranked.hs
@@ -61,7 +61,8 @@ rindexPartial (Ranked arr) idx =
             (ixxFromIxR idx))
 
 -- | __WARNING__: All values returned from the function must have equal shape.
--- See the documentation of 'mgenerate' for more details.
+-- See the documentation of 'mgenerate' for more details; see also
+-- 'rgeneratePrim'.
 rgenerate :: forall n a. KnownElt a => IShR n -> (IIxR n -> a) -> Ranked n a
 rgenerate sh f
   | sn@SNat <- shrRank sh
-- 
cgit v1.2.3-70-g09d2