Update documentation

Fix changelog
Add examples for sorting functions

CHANGELOG.md

@@ -1,6 +1,6 @@
 # 0.2.2.1 - July 2024
 
-* Add `sort`, `sortBy`, `sortOn` ([#23](https://github.com/konsumlamm/rrb-vector/pull/22))
+* Add `sort`, `sortBy`, `sortOn` ([#23](https://github.com/konsumlamm/rrb-vector/pull/23))
 * Fix bug in `><` ([#19](https://github.com/konsumlamm/rrb-vector/pull/19))
 * Fix bug in `<|` ([#18](https://github.com/konsumlamm/rrb-vector/pull/18))
 

src/Data/RRBVector.hs

@@ -46,7 +46,8 @@ module Data.RRBVector
     , zip, zipWith, unzip, unzipWith
     -- * Sorting
     --
-    -- | Currently implemented using [samsort](https://hackage.haskell.org/package/samsort).
+    -- | The sorting functions are currently implemented using the
+    -- [samsort](https://hackage.haskell.org/package/samsort) library.
     , sort, sortBy, sortOn
     ) where
 

src/Data/RRBVector/Internal.hs

@@ -90,15 +90,19 @@ data Vector a
         !Shift -- shift (blockShift * height)
         !(Tree a)
 
--- The number of bits used per level.
+-- | The number of bits used per level.
 blockShift :: Shift
 blockShift = 4
 
--- The maximum size of a block.
+-- | The maximum size of a block.
+--
+-- > blockSize = 2 ^ blockShift
 blockSize :: Int
 blockSize = 1 `unsafeShiftL` blockShift
 
--- The mask used to extract the index into the array.
+-- | The mask used to extract the index into the array.
+--
+-- > blockMask = blockSize - 1
 blockMask :: Int
 blockMask = blockSize - 1
 
@@ -143,7 +147,7 @@ treeSize = go 0
         in go (acc + i * (1 `unsafeShiftL` sh)) (down sh) (A.index arr i)
 {-# INLINE treeSize #-}
 
--- @computeSizes sh@ turns an array into a tree node by computing the sizes of its subtrees.
+-- | @computeSizes sh@ turns an array into a tree node by computing the sizes of its subtrees.
 -- @sh@ is the shift of the resulting tree.
 computeSizes :: Shift -> A.Array (Tree a) -> Tree a
 computeSizes !sh arr
@@ -555,10 +559,16 @@ reverse v
 
 -- | \(O(\min(n_1, n_2))\). Take two vectors and return a vector of corresponding pairs.
 -- If one input is longer, excess elements are discarded from the right end.
+--
+-- >>> zip (fromList [1, 2, 3]) (fromList ['a', 'b'])
+-- fromList [(1,'a'),(2,'b')]
 zip :: Vector a -> Vector b -> Vector (a, b)
 zip v1 v2 = fromList $ List.zip (toList v1) (toList v2)
 
 -- | \(O(\min(n_1, n_2))\). 'zipWith' generalizes 'zip' by zipping with the function.
+--
+-- >>> zipWith (++) (fromList ["a", "b", "c"]) (fromList ["d", "e"])
+-- fromList ["ad","be"]
 zipWith :: (a -> b -> c) -> Vector a -> Vector b -> Vector c
 zipWith f v1 v2 = fromList $ List.zipWith f (toList v1) (toList v2)
 

src/Data/RRBVector/Internal/Sorting.hs

@@ -21,13 +21,19 @@ uninitialized = errorWithoutStackTrace "uninitialized"
 -- | \(O(n \log n)\). Sort the vector in ascending order.
 -- The sort is stable, meaning the order of equal elements is preserved.
 --
+-- >>> sort (fromList [3, 1, 2])
+-- fromList [1,2,3]
+--
 -- @since 0.2.2.0
 sort :: (Ord a) => Vector a -> Vector a
 sort = sortBy compare
 
 -- | \(O(n \log n)\). Sort the vector in ascending order according to the specified comparison function.
 -- The sort is stable, meaning the order of equal elements is preserved.
 --
+-- >>> sortBy compare (fromList [3, 1, 2])
+-- fromList [1,2,3]
+--
 -- @since 0.2.2.0
 sortBy :: (a -> a -> Ordering) -> Vector a -> Vector a
 sortBy cmp v =
@@ -40,6 +46,10 @@ sortBy cmp v =
 -- The sort is stable, meaning the order of equal elements is preserved.
 -- @`sortOn` f@ is equivalent to @`sortBy` (`Data.Ord.comparing` f)@, but only evaluates @f@ once for each element.
 --
+-- >>> import Data.Ord (Down(..))
+-- >>> sortOn Down (fromList [3, 1, 2])
+-- fromList [3,2,1]
+--
 -- @since 0.2.2.0
 sortOn :: (Ord b) => (a -> b) -> Vector a -> Vector a
 sortOn f v =