Improve haddocs following the Tom's guidancemvecsReplicate

2 files changed, 6 insertions, 12 deletions

diff --git a/src/Data/Array/Nested/Mixed/ListX.hs b/src/Data/Array/Nested/Mixed/ListX.hs
index e4e224b..2c8a9cc 100644
--- a/src/Data/Array/Nested/Mixed/ListX.hs
+++ b/src/Data/Array/Nested/Mixed/ListX.hs
@@ -48,7 +48,8 @@ type family Rank sh where
 
 -- * Mixed lists implementation
 
--- | Data invariant: each element is in WHNF (the spine may be be not forced).
+-- | Data invariant: each element on the list is in WHNF (the spine may be lazy)
+-- and the length of the list is the same as of the type-level shape.
 type role ListX nominal representational
 type ListX :: [Maybe Nat] -> Type -> Type
 newtype ListX sh i = ListX [i]
@@ -83,24 +84,17 @@ listxUncons (ListX []) = Nothing
 
 {-# COMPLETE ZX, (::%) #-}
 
--- | This operation may not preserve the data invariant for ListX,
--- regardless whether the invariant holds for the argument list.
--- It's the user's obligation to honor the data invariant,
--- e.g., by forcing all new elements of the resulting list at the end.
+-- | This function makes no attempt to stop you from breaking the data invariant for 'ListX'. If you do so, you must later ensure that the invariant is reinstated, for example using @'lazilyForce' 'id'@.
 {-# INLINE lazily #-}
 lazily :: ([a] -> [b]) -> ListX sh a -> ListX sh b
 lazily f (ListX l) = ListX $ f l
 
--- | This operation may not preserve the data invariant for ListX,
--- regardless whether the invariant holds for the argument lists.
--- It's the user's obligation to honor the data invariant,
--- e.g., by forcing all new elements of the resulting list at the end.
+-- | This function makes no attempt to stop you from breaking the data invariant for 'ListX'. If you do so, you must later ensure that the invariant is reinstated, for example using @'lazilyForce' 'id'@.
 {-# INLINE lazilyConcat #-}
 lazilyConcat :: ([a] -> [b] -> [c]) -> ListX sh a -> ListX sh' b -> ListX (sh ++ sh') c
 lazilyConcat f (ListX l) (ListX k) = ListX $ f l k
 
--- | This operation honours the data invariant for @ListX@ by forcing
--- all elements of the resulting list at the end.
+-- | This operation forces all elements of the @[b]@ list to restore the strictness part of the data invariant for 'ListX'. Note that ensuring the list has the right length is still the user's responsibility.
 {-# INLINE lazilyForce #-}
 lazilyForce :: ([a] -> [b]) -> ListX sh a -> ListX sh b
 lazilyForce f (ListX l) = let res = f l
diff --git a/src/Data/Array/Nested/Permutation.hs b/src/Data/Array/Nested/Permutation.hs
index 19d81f0..85fbd89 100644
--- a/src/Data/Array/Nested/Permutation.hs
+++ b/src/Data/Array/Nested/Permutation.hs
@@ -313,7 +313,7 @@ permId n = go SZ
            else gcastWith (unsafeCoerceRefl :: (l :~: k : anything)) $
                 k `PCons` go (SS k)
 
--- Note that the second argument is not a valid permutation.
+-- | Note that the second argument is not a valid permutation.
 permAppend :: Perm l -> Perm l2 -> Perm (l ++ l2)
 permAppend PNil l2 = l2
 permAppend (n `PCons` rest) l2 = n `PCons` permAppend rest l2