Merge pull request #117 from kaBeech/update-docs

Update docs

CHANGELOG.md

@@ -85,10 +85,10 @@
 
 * Cleanup code and documentation a bit
 
-## X.X.X.X -- XXXX.XX.XX
+## 1.0.1.3 -- 2024-09-16
 
 * Adjust README formatting
 
 * Add Hype section to README
 
-* Some code cleanup
+* Some code and documentation cleanup

README.md

@@ -170,8 +170,11 @@ falter without:
 
 <figure>
     <img src="./assets/images/ackley_deps.png"
-         alt="Comment from Ackley in the Beyond Efficiency code about Perl
-        updates breaking their code">
+         alt="A screenshot from Ackley's code referenced in 'Beyond Efficiency':
+             'Written by Dave Ackley in 2011-2012 and placed in the public
+              domain. Gah!  Perl has messed with its sorting algorithms in
+              COMPLETELY NON-BACKWARD-COMPATIBLE WAYS!  So require our version
+              (more or less, anyway) to try to stabilize these results!'">
     <figcaption><i><a href="http://livingcomputation.com/robusort2.tar" 
                       rel="noopener noreferrer"
                       target="_blank">
@@ -1176,4 +1179,13 @@ I'd like to send a special thank you to the following people:
 
 ## Hype
 
-  - Dave Ackley read my paper!! And had [this](https://hachyderm.io/@livcomp/113016513691522706) to say about it: "Super great stuff! kabeech dives into iid errors in comparison sorting, ropes it, pulls it down, and hogties it six ways to Sunday."
+  - Dave Ackley read my paper!! And had 
+    [this](https://hachyderm.io/@livcomp/113016513691522706) to say about it:
+    "Super great stuff! kabeech dives into iid errors in comparison sorting,
+    ropes it, pulls it down, and hogties it six ways to Sunday."
+
+  - Ivan Reese also had
+    [very kind](https://futureofcoding.slack.com/archives/CCL5VVBAN/p1724550313800559?thread_ts=1724444821.212869&cid=CCL5VVBAN)
+    things to say: "Hats off Kyle. You've made something very cool and
+    technical and fascinating, but also woven charm and joy into its
+    presentation. Beautiful."

src/Data/Tensort/OtherSorts/Mergesort.hs

@@ -1,11 +1,12 @@
--- | This module provides the mergesort function for sorting lists using the
---   Sortable type
+-- | This module provides an implementation of the mergesort algorithm suitable
+--   for sorting lists using the Sortable type.
 module Data.Tensort.OtherSorts.Mergesort (mergesort) where
 
 import Data.Tensort.Utils.ComparisonFunctions (lessThanBit, lessThanRecord)
 import Data.Tensort.Utils.Types (Bit, Record, Sortable (..))
 
--- | Takes a Sortable and returns a sorted Sortable using a Mergesort algorithm
+-- | Takes a Sortable and returns a sorted Sortable using a Mergesort
+--   algorithm.
 
 -- | ==== __Examples__
 --  >>> mergesort (SortBit [16, 23, 4, 8, 15, 42])

src/Data/Tensort/OtherSorts/Quicksort.hs

@@ -1,11 +1,12 @@
--- | This module provides the quicksort function for sorting lists using the
---   Sortable type
+-- | This module provides an implementation of the quicksort algorithm suitable
+--   for sorting lists using the Sortable type.
 module Data.Tensort.OtherSorts.Quicksort (quicksort) where
 
 import Data.Tensort.Utils.ComparisonFunctions (greaterThanBit, greaterThanRecord)
 import Data.Tensort.Utils.Types (Bit, Record, Sortable (..))
 
--- | Takes a Sortable and returns a sorted Sortable using a Quicksort algorithm
+-- | Takes a Sortable and returns a sorted Sortable using a Quicksort
+--   algorithm.
 
 -- | ==== __Examples__
 --  >>> quicksort (SortBit [16, 23, 4, 8, 15, 42])

src/Data/Tensort/Robustsort.hs

@@ -1,5 +1,5 @@
 -- | This module provides variations of the Robustsort algorithm using the
---   Sortable type
+--   custom Sortable type for inputs and outputs
 module Data.Tensort.Robustsort
   ( robustsortP,
     robustsortB,
@@ -138,11 +138,11 @@ supersortM =
 --   the base SortAlg to sort the records.
 --
 --   Uses the base SortAlg once the bytesize is less than or equal to 27. This
---   number is chosen because it is the natural logarithm of 27 is close to
---   3 (it's abuot 3.3) and the square root of 27 is 3, so it's likely to be an
---   efficient choice.
+--   number is chosen because the natural logarithm of 27 is close to 3 (it's
+--   about 3.3) and the cube root of 27 is 3, so it's likely to be an efficient
+--   choice.
 --
---   This confiuguration is tailored to using a standard basic Robustsort
+--   This configuration is tailored to using a standard basic Robustsort
 --   algorithm (i.e. with a Bytesize of 3) as the base SortAlg. You're welcome
 --   to experiment with weirder setups too!
 --
@@ -161,15 +161,22 @@ robustsortRCustom baseSortAlg xs =
     )
     xs
 
+-- | Used to create SubAlgorithms for use in recursive Robustsort variants. See
+--   also `robustsortRCustom`.
+--
+--   Creates an algorithm that recursively applies Tensort with a Bytesize that
+--   approximates the natural logarithm of the length of the input list until
+--   the Bytesize is less than or equal to 27. At this point, the baseSortAlg
+--   is used to sort the records.
 robustsortRecursive :: Int -> SortAlg -> SortAlg
 robustsortRecursive bytesize baseSortAlg
   -- ln (532048240602) ~= 27
   -- ln (27) ~= 3
   -- 3 ^ 3 = 27
   -- So this is saying, if we have a bitesize of 532,048,240,602 or less, use
   -- one more iteration of Tensort to sort the records. This last iteration
-  -- will use the baseSortAlg (which by default is a standard version of
-  -- Robustsort with a bytesize of 3) to sort its records.
+  -- will use the baseSortAlg (such as the basic version of Robustsort with
+  -- bytesize of 3 used in this module) to sort its records.
   | bytesize <= 27 = baseSortAlg
   | otherwise =
       tensort

src/Data/Tensort/Subalgorithms/Bogosort.hs

@@ -1,31 +1,29 @@
--- | This module provides the bogosort function for sorting lists using the
---   Sortable type
+-- | This module provides the bogosort function for sorting Sortable lists
 module Data.Tensort.Subalgorithms.Bogosort (bogosort, bogosortSeeded) where
 
 import Data.Tensort.Utils.Check (isSorted)
 import Data.Tensort.Utils.RandomizeList (randomizeList)
 import Data.Tensort.Utils.Types (Sortable (..))
 
--- | Takes a Sortable and returns a sorted Sortable using a Bogosort algorithm
---   using the default seed for random generation
+-- | Takes a Sortable and returns a sorted Sortable using a Bogosort algorithm.
 
 -- | ==== __Examples__
 -- >>> bogosort (SortBit [16, 23, 4, 8, 15, 42])
 -- SortBit [4,8,15,16,23,42]
 --
--- >>> bogosort (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15) , (4, 42)])
+-- >>> bogosort (SortRec [(1, 16), (5, 23), (2, 4), (3, 8), (0, 15), (4, 42)])
 -- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)]
 bogosort :: Sortable -> Sortable
 bogosort = bogosortSeeded 143
 
 -- | Takes a seed for use in random generation and a Sortable and returns a
---  sorted Sortable using a Bogosort algorithm
+--  sorted Sortable using a Bogosort algorithm.
 
 -- | ==== __Examples__
 -- >>> bogosortSeeded 42 (SortBit [16, 23, 4, 8, 15, 42])
 -- SortBit [4,8,15,16,23,42]
 --
--- >>> bogosortSeeded 24 (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15) , (4, 42)])
+-- >>> bogosortSeeded 24 (SortRec [(1, 16), (5, 23), (2, 4), (3, 8), (0, 15), (4, 42)])
 -- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)]
 bogosortSeeded :: Int -> Sortable -> Sortable
 bogosortSeeded seed xs

src/Data/Tensort/Subalgorithms/Bubblesort.hs

@@ -1,5 +1,4 @@
--- | This module provides the bubblesort function for sorting lists using the
---   Sortable type
+-- | This module provides the bubblesort function for sorting Sortable lists
 module Data.Tensort.Subalgorithms.Bubblesort (bubblesort) where
 
 import Data.Tensort.Utils.ComparisonFunctions
@@ -9,13 +8,13 @@ import Data.Tensort.Utils.ComparisonFunctions
 import Data.Tensort.Utils.Types (Sortable (..))
 
 -- | Takes a Sortable and returns a sorted Sortable using a Bubblesort
--- algorithm
+--   algorithm.
 
 -- | ==== __Examples__
 -- >>> bubblesort (SortBit [16, 23, 4, 8, 15, 42])
 -- SortBit [4,8,15,16,23,42]
 --
--- >>> bubblesort (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15) , (4, 42)])
+-- >>> bubblesort (SortRec [(1, 16), (5, 23), (2, 4), (3, 8), (0, 15), (4, 42)])
 -- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)]
 bubblesort :: Sortable -> Sortable
 bubblesort (SortBit bits) =

src/Data/Tensort/Subalgorithms/Exchangesort.hs

@@ -1,12 +1,11 @@
--- | This module provides the bubblesort function for sorting lists using the
---   Sortable type
+-- | This module provides the bubblesort function for sorting Sortable lists
 module Data.Tensort.Subalgorithms.Exchangesort (exchangesort) where
 
 import Data.Tensort.Utils.ComparisonFunctions (greaterThanBit, greaterThanRecord)
 import Data.Tensort.Utils.Types (Sortable (..))
 
 -- | Takes a Sortable and returns a sorted Sortable using an Exchangesort
---   algorithm
+--   algorithm.
 
 -- | ==== __Examples__
 -- >>> exchangesort (SortBit [16, 23, 4, 8, 15, 42])

src/Data/Tensort/Subalgorithms/Magicsort.hs

@@ -1,5 +1,4 @@
--- | This module provides the magicsort function for sorting lists using the
---   Sortable type
+-- | This module provides the magicsort function for sorting Sortable lists
 module Data.Tensort.Subalgorithms.Magicsort
   ( magicsort,
   )
@@ -9,16 +8,17 @@ import Data.Tensort.Subalgorithms.Bogosort (bogosort)
 import Data.Tensort.Subalgorithms.Permutationsort (permutationsort)
 import Data.Tensort.Utils.Types (Sortable (..))
 
--- | Takes a Sortable and returns a sorted Sortable
+-- | Takes a Sortable and returns a sorted Sortable.
 --
---   Adjudicates between three other sorting algorithms to return a robust
---   solution
+--   Runs both Permutationsort and Bogosort on the input Sortable and compares
+--   the results. If the results agree, returns the result of Permutationsort,
+--   otherwise repeats the process.
 
 -- | ==== __Examples__
 -- >>> magicsort (SortBit [16, 23, 4, 8, 15, 42])
 -- SortBit [4,8,15,16,23,42]
 --
--- >>> magicsort (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15) , (4, 42)])
+-- >>> magicsort (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15), (4, 42)])
 -- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)]
 magicsort :: Sortable -> Sortable
 magicsort xs = do

src/Data/Tensort/Subalgorithms/Permutationsort.hs

@@ -1,5 +1,5 @@
--- | This module provides the permutationsort function for sorting lists using the
---   Sortable type
+-- | This module provides the permutationsort function for sorting Sortable
+--   lists
 module Data.Tensort.Subalgorithms.Permutationsort (permutationsort) where
 
 import Data.List (permutations)
@@ -12,7 +12,7 @@ import Data.Tensort.Utils.Types
     fromSortRec,
   )
 
--- | Takes a Sortable and returns a sorted Sortable using a Permutationsort
+-- | Takes a Sortable and returns a sorted Sortable using Permutationsort
 --   algorithm
 
 -- | ==== __Examples__

src/Data/Tensort/Subalgorithms/Rotationsort.hs

@@ -1,5 +1,4 @@
--- | This module provides Rotationsort variants for sorting lists using the
---   Sortable type
+-- | This module provides Rotationsort variants for sorting Sortable lists.
 --
 -- | I was having some issues with the swaps for larger input lists, so for now
 --   these functions are only implemented for lists of length 3 or less.
@@ -18,7 +17,7 @@ import Data.Tensort.Utils.ComparisonFunctions
 import Data.Tensort.Utils.Types (Sortable (..))
 
 -- | Takes a Sortable and returns a sorted Sortable using a Rotationsort
---  algorithm
+--  algorithm.
 --
 --  I was having some issues with the swaps for larger input lists, so for now
 --  this function is only implemented for lists of length 3 or less.
@@ -40,7 +39,7 @@ rotationsort (SortRec recs) =
    in SortRec result
 
 -- | Takes a Sortable and returns a sorted Sortable using an Ambidextrous
---   Rotationsort algorithm
+--   Rotationsort algorithm.
 --
 --  I was having some issues with the swaps for larger input lists, so for now
 --  this function is only implemented for lists of length 3 or less.
@@ -62,7 +61,7 @@ rotationsortAmbi (SortRec recs) =
    in SortRec result
 
 -- | Takes a Sortable and returns a sorted Sortable using a Reverse
---   Rotationsort algorithm
+--   Rotationsort algorithm.
 --
 --   I was having some issues with the swaps for larger input lists, so for now
 --   this function is only implemented for lists of length 3 or less.
@@ -94,7 +93,7 @@ rotationsortReverse (SortRec recs) =
    in SortRec result
 
 -- | Takes a Sortable and returns a sorted Sortable using an Ambidextrous
---   Reverse Rotationsort algorithm
+--   Reverse Rotationsort algorithm.
 --
 --   I was having some issues with the swaps for larger input lists, so for now
 --   this function is only implemented for lists of length 3 or less.

src/Data/Tensort/Subalgorithms/Supersort.hs

@@ -1,5 +1,5 @@
 -- | This module provides functions for creating Supersort variants for
---   adjudicating between 3 sorting algorithms that use the Sortable type
+--   adjudicating between 3 sorting algorithms.
 module Data.Tensort.Subalgorithms.Supersort
   ( supersort,
     mundaneSuperStrat,
@@ -13,8 +13,12 @@ import Data.Tensort.Utils.Types
     SupersortStrat,
   )
 
--- | Takes 3 sorting algorithms and a SuperStrat and returns a SortAlg that
---   adjudicates between the 3 sorting algorithms using the provided SuperStrat
+-- | Used for creating a Supersort algorithm that adjudicates between 3 sorting
+--   algorithms.
+--
+--   Takes 3 sorting algorithms and a SuperStrat and returns a SortAlg that
+--   adjudicates between the 3 sorting algorithms using the provided
+--   SuperStrat.
 
 -- | ==== __Examples__
 -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort)
@@ -37,8 +41,8 @@ supersort (subAlg1, subAlg2, subAlg3, superStrat) xs = do
     then result1
     else superStrat (result1, result2, subAlg3 xs)
 
--- | Takes 3 SortAlgs and adjudicates between them to find a common result to
---   increase robustness
+-- | Takes 3 SortAlgs and adjudicates between them to find a common result.
+--   Optimized for use in Mundane Robustsort variants.
 
 -- | ==== __Examples__
 -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort)
@@ -53,12 +57,12 @@ supersort (subAlg1, subAlg2, subAlg3, superStrat) xs = do
 mundaneSuperStrat :: SupersortStrat
 mundaneSuperStrat (result1, result2, result3) = if result2 == result3 then result2 else result1
 
--- | Takes 3 SortAlgs and adjudicates between them to find a common result to
---   increase robustness
+-- | Takes 3 SortAlgs and adjudicates between them to find a common result.
+--   Optimized for use in Magic Robustsort variants.
 --
 --   Previously we used different SuperStrats for Mundane and Magic Supersorts.
 --   Currently there is no need to differentiate, but we keep this here for
---   backwards compatibility and in case this changes again in the future
+--   backwards compatibility and in case this changes again in the future.
 
 -- | ==== __Examples__
 -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort)

src/Data/Tensort/Tensort.hs

@@ -1,5 +1,5 @@
 -- | This module provides variations of the Tensort algorithm using the
---   Sortable type
+--   custom Sortable type for inputs and outputs
 module Data.Tensort.Tensort
   ( tensort,
     tensortB4,
@@ -25,7 +25,8 @@ import Data.Tensort.Utils.Types
 
 -- | Sort a Sortable list using a custom Tensort algorithm
 --
---   Takes TensortProps and a Sortable and returns a sorted Sortable
+--   Takes TensortProps (Bytesize and SubAlgorithm) and a Sortable and returns
+--   a sorted Sortable
 
 -- | ==== __Examples__
 -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort)
@@ -80,6 +81,9 @@ tensortBN :: Int -> Sortable -> Sortable
 tensortBN n = tensort (mkTsProps n bubblesort)
 
 -- | Sort a Sortable list using a Standard Logarithmic Tensort algorithm
+--
+--   Standard Logarithmic Tensort uses a Bytesize that approximates the natural
+--   logarithm of the length of the input list and a Bubblesort subalgorithm
 
 -- | ==== __Examples__
 -- >>> tensortBL (SortBit [16, 23, 4, 8, 15, 42])