Merge pull request #92 from kaBeech/update-docs

Update docs

src/Data/Robustsort.hs

@@ -1,3 +1,5 @@
+-- | This module provides convenience functions that wraps common Robustsort
+--   functions to sort lists of Bits without dealing with type conversion
 module Data.Robustsort
   ( robustsortP,
     robustsortB,
@@ -19,20 +21,74 @@ import qualified Data.Tensort.Robustsort
 import Data.Tensort.Utils.Types (Bit)
 import Data.Tensort.Utils.WrapSortAlg (wrapSortAlg)
 
+-- | Takes a list of Bits and returns a sorted list of Bits using a Basic
+--   Mundane Robustsort algorithm with a Permutationsort adjudicator
+--
+-- | This is a convenience function that wraps the
+--   'Data.Tensort.Robustsort.robustsortP' function
+
+-- | ==== __Examples__
+--   >>> robustsortP [16, 23, 4, 8, 15, 42]
+--   [4,8,15,16,23,42]
 robustsortP :: [Bit] -> [Bit]
 robustsortP = wrapSortAlg Data.Tensort.Robustsort.robustsortP
 
+-- | Takes a list of Bits and returns a sorted list of Bits using a Basic
+--   Mundane Robustsort algorithm with a Bogosort adjudicator
+--
+-- | This is a convenience function that wraps the
+--   'Data.Tensort.Robustsort.robustsortB' function
+
+-- | ==== __Examples__
+--  >>> robustsortB [16, 23, 4, 8, 15, 42]
+--  [4,8,15,16,23,42]
 robustsortB :: [Bit] -> [Bit]
 robustsortB = wrapSortAlg Data.Tensort.Robustsort.robustsortB
 
+-- | Takes a list of Bits and returns a sorted list of Bits using a Basic
+--   Magic Robustsort algorithm
+--
+-- | This is a convenience function that wraps the
+--   'Data.Tensort.Robustsort.robustsortM' function
+
+-- | ==== __Examples__
+--  >>> robustsortM [16, 23, 4, 8, 15, 42]
+--  [4,8,15,16,23,42]
 robustsortM :: [Bit] -> [Bit]
 robustsortM = wrapSortAlg Data.Tensort.Robustsort.robustsortM
 
+-- | Takes a list of Bits and returns a sorted list of Bits using a Recursive
+--   Mundane Robustsort algorithm with a Permutationsort adjudicator
+--
+--  | This is a convenience function that wraps the
+--    'Data.Tensort.Robustsort.robustsortRP' function
+
+--  | ==== __Examples__
+--  >>> robustsortRP [16, 23, 4, 8, 15, 42]
+--  [4,8,15,16,23,42]
 robustsortRP :: [Bit] -> [Bit]
 robustsortRP = wrapSortAlg Data.Tensort.Robustsort.robustsortRP
 
+-- | Takes a list of Bits and returns a sorted list of Bits using a Recursive
+--  Mundane Robustsort algorithm with a Bogosort adjudicator
+--
+--  | This is a convenience function that wraps the
+--  'Data.Tensort.Robustsort.robustsortRB' function
+
+--  | ==== __Examples__
+--  >>> robustsortRB [16, 23, 4, 8, 15, 42]
+--  [4,8,15,16,23,42]
 robustsortRB :: [Bit] -> [Bit]
 robustsortRB = wrapSortAlg Data.Tensort.Robustsort.robustsortRB
 
+-- | Takes a list of Bits and returns a sorted list of Bits using a Recursive
+--   Magic Robustsort algorithm
+--
+--   | This is a convenience function that wraps the
+--   'Data.Tensort.Robustsort.robustsortRM' function
+
+--   | ==== __Examples__
+--   >>> robustsortRM [16, 23, 4, 8, 15, 42]
+--   [4,8,15,16,23,42]
 robustsortRM :: [Bit] -> [Bit]
 robustsortRM = wrapSortAlg Data.Tensort.Robustsort.robustsortRM

src/Data/Tensort.hs

@@ -1,3 +1,5 @@
+-- | This module provides convenience functions that wraps common Tensort
+--   functions to sort lists of Bits without dealing with type conversion
 module Data.Tensort
   ( tensort,
   )
@@ -7,5 +9,13 @@ import Data.Tensort.Tensort (tensortBL)
 import Data.Tensort.Utils.Types (Bit)
 import Data.Tensort.Utils.WrapSortAlg (wrapSortAlg)
 
+-- | Takes a list of Bits and returns a sorted list of Bits using a Standard
+--   Logarithmic Tensort algorithm
+--
+-- | This is a convenience function that wraps the 'tensortBL' function
+
+-- | ==== __Examples__
+--   >>> tensort [16, 23, 4, 8, 15, 42]
+--   [4,8,15,16,23,42]
 tensort :: [Bit] -> [Bit]
 tensort = wrapSortAlg tensortBL

src/Data/Tensort/OtherSorts/Mergesort.hs

@@ -1,8 +1,18 @@
+-- | This module provides the mergesort function 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 (Record, Sortable (..), Bit)
+import Data.Tensort.Utils.Types (Bit, Record, Sortable (..))
 
+-- | Takes a Sortable and returns a sorted Sortable using a Mergesort algorithm
+
+-- | ==== __Examples__
+--  >>> mergesort (SortBit [16, 23, 4, 8, 15, 42])
+--  SortBit [4,8,15,16,23,42]
+--
+--  >>> mergesort (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)]
 mergesort :: Sortable -> Sortable
 mergesort (SortBit xs) = SortBit (mergesortBits xs)
 mergesort (SortRec xs) = SortRec (mergesortRecs xs)

src/Data/Tensort/OtherSorts/Quicksort.hs

@@ -1,8 +1,18 @@
+-- | This module provides the quicksort function 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
+
+-- | ==== __Examples__
+--  >>> quicksort (SortBit [16, 23, 4, 8, 15, 42])
+--  SortBit [4,8,15,16,23,42]
+--
+--  >>> quicksort (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)]
 quicksort :: Sortable -> Sortable
 quicksort (SortBit []) = SortBit []
 quicksort (SortBit [x]) = SortBit [x]

src/Data/Tensort/Robustsort.hs

@@ -1,3 +1,5 @@
+-- | This module provides variations of the Robustsort algorithm using the
+--   Sortable type
 module Data.Tensort.Robustsort
   ( robustsortP,
     robustsortB,
@@ -27,9 +29,21 @@ import Data.Tensort.Tensort (tensort)
 import Data.Tensort.Utils.MkTsProps (mkTsProps)
 import Data.Tensort.Utils.Types (SortAlg, Sortable (..))
 
+-- | Takes a Sortable and returns a sorted Sortable using a Recursive Mundane
+--   Robustsort algorithm with a Permutationsort adjudicator
+
+-- | ==== __Examples__
+--  >>> robustsortRP (SortBit [16, 23, 4, 8, 15, 42])
+--  SortBit [4,8,15,16,23,42]
 robustsortRP :: Sortable -> Sortable
 robustsortRP = robustsortRCustom robustsortP
 
+-- | Takes a Sortable and returns a sorted Sortable using a Basic Mundane
+--   Robustsort algorithm with a Permutationsort adjudicator
+
+-- | ==== __Examples__
+-- >>> robustsortP (SortBit [16, 23, 4, 8, 15, 42])
+-- SortBit [4,8,15,16,23,42]
 robustsortP :: Sortable -> Sortable
 robustsortP = tensort (mkTsProps 3 supersortP)
 
@@ -42,9 +56,21 @@ supersortP =
       mundaneSuperStrat
     )
 
+-- | Takes a Sortable and returns a sorted Sortable using a Recursive Mundane
+--   Robustsort algorithm with a Bogosort adjudicator
+
+-- | ==== __Examples__
+-- >>> robustsortRB (SortBit [16, 23, 4, 8, 15, 42])
+-- SortBit [4,8,15,16,23,42]
 robustsortRB :: Sortable -> Sortable
 robustsortRB = robustsortRCustom robustsortB
 
+-- | Takes a Sortable and returns a sorted Sortable using a Basic Mundane
+--   Robustsort algorithm with a Bogosort adjudicator
+
+-- | ==== __Examples__
+-- >>> robustsortB (SortBit [16, 23, 4, 8, 15, 42])
+-- SortBit [4,8,15,16,23,42]
 robustsortB :: Sortable -> Sortable
 robustsortB = tensort (mkTsProps 3 supersortB)
 
@@ -57,9 +83,21 @@ supersortB =
       mundaneSuperStrat
     )
 
+-- | Takes a Sortable and returns a sorted Sortable using a Recursive Magic
+--   Robustsort algorithm
+
+-- | ==== __Examples__
+-- >>> robustsortRM (SortBit [16, 23, 4, 8, 15, 42])
+-- SortBit [4,8,15,16,23,42]
 robustsortRM :: Sortable -> Sortable
 robustsortRM = robustsortRCustom robustsortM
 
+-- | Takes a Sortable and returns a sorted Sortable using a Basic Magic
+--   Robustsort algorithm
+
+-- | ==== __Examples__
+-- >>> robustsortM (SortBit [16, 23, 4, 8, 15, 42])
+-- SortBit [4,8,15,16,23,42]
 robustsortM :: Sortable -> Sortable
 robustsortM = tensort (mkTsProps 3 supersortM)
 
@@ -72,6 +110,7 @@ supersortM =
       magicSuperStrat
     )
 
+-- | Used for making recursive Robustsort algorithms
 robustsortRCustom :: SortAlg -> Sortable -> Sortable
 robustsortRCustom baseSortAlg xs =
   tensort

src/Data/Tensort/Subalgorithms/Bogosort.hs

@@ -1,12 +1,32 @@
+-- | This module provides the bogosort function for sorting lists using the
+--   Sortable type
 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
+
+-- | ==== __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)])
+-- 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
+
+-- | ==== __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)])
+-- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)]
 bogosortSeeded :: Int -> Sortable -> Sortable
 bogosortSeeded seed xs
   | isSorted xs = xs

src/Data/Tensort/Subalgorithms/Bubblesort.hs

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

src/Data/Tensort/Subalgorithms/Exchangesort.hs

@@ -1,8 +1,19 @@
+-- | This module provides the bubblesort function for sorting lists using the
+--   Sortable type
 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
+
+-- | ==== __Examples__
+-- >>> exchangesort (SortBit [16, 23, 4, 8, 15, 42])
+-- SortBit [4,8,15,16,23,42]
+--
+-- >>> exchangesort (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)]
 exchangesort :: Sortable -> Sortable
 exchangesort (SortBit bits) = SortBit (exchangesortIterable greaterThanBit bits 0 (length bits - 1))
 exchangesort (SortRec recs) = SortRec (exchangesortIterable greaterThanRecord recs 0 (length recs - 1))

src/Data/Tensort/Subalgorithms/Magicsort.hs

@@ -1,3 +1,5 @@
+-- | This module provides the magicsort function for sorting lists using the
+--   Sortable type
 module Data.Tensort.Subalgorithms.Magicsort
   ( magicsort,
   )
@@ -7,6 +9,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
+--
+-- | Adjudicates between three other sorting algorithms to return a robust
+--   solution
+
+-- | ==== __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)])
+-- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)]
 magicsort :: Sortable -> Sortable
 magicsort xs = do
   let result1 = permutationsort xs

src/Data/Tensort/Subalgorithms/Permutationsort.hs

@@ -1,23 +1,42 @@
+-- | This module provides the permutationsort function for sorting lists using the
+--   Sortable type
 module Data.Tensort.Subalgorithms.Permutationsort (permutationsort) where
 
 import Data.List (permutations)
 import Data.Tensort.Utils.Check (isSorted)
-import Data.Tensort.Utils.Types (Record, Sortable (..), fromSortBit, fromSortRec, Bit)
+import Data.Tensort.Utils.Types
+  ( Bit,
+    Record,
+    Sortable (..),
+    fromSortBit,
+    fromSortRec,
+  )
 
+-- | Takes a Sortable and returns a sorted Sortable using a Permutationsort
+--   algorithm
+
+-- | ==== __Examples__
+-- >>> permutationsort (SortBit [16, 23, 4, 8, 15, 42])
+-- SortBit [4,8,15,16,23,42]
+--
+-- >>> permutationsort (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)]
 permutationsort :: Sortable -> Sortable
 permutationsort (SortBit xs) = SortBit (acc (permutations x) [])
   where
     x = xs
     acc :: [[Bit]] -> [Bit] -> [Bit]
-    acc [] unsortedPermutations = fromSortBit (permutationsort (SortBit unsortedPermutations))
+    acc [] unsortedPermutations =
+      fromSortBit (permutationsort (SortBit unsortedPermutations))
     acc (permutation : remainingPermutations) unsortedPermutations
       | isSorted (SortBit permutation) = permutation
       | otherwise = acc remainingPermutations unsortedPermutations
 permutationsort (SortRec xs) = SortRec (acc (permutations x) [])
   where
     x = xs
     acc :: [[Record]] -> [Record] -> [Record]
-    acc [] unsortedPermutations = fromSortRec (permutationsort (SortRec unsortedPermutations))
+    acc [] unsortedPermutations =
+      fromSortRec (permutationsort (SortRec unsortedPermutations))
     acc (permutation : remainingPermutations) unsortedPermutations
       | isSorted (SortRec permutation) = permutation
       | otherwise = acc remainingPermutations unsortedPermutations