Haddock for Sampler.

internal/Data/Boltzmann/Sampler.hs

@@ -1,14 +1,19 @@
 -- |
 -- Module      : Data.Boltzmann.Sampler
--- Description : Boltzmann sampler for specifiable types.
+-- Description :
 -- Copyright   : (c) Maciej Bendkowski, 2022
 -- License     : BSD3
 -- Maintainer  : maciej.bendkowski@gmail.com
 -- Stability   : experimental
 module Data.Boltzmann.Sampler (
+  -- * Boltzmann samplers
   BoltzmannSampler (..),
+
+  -- * Rejection samplers
   rejectionSampler,
   toleranceRejectionSampler,
+
+  -- * Other utilities
   hoistBoltzmannSampler,
 ) where
 
@@ -21,8 +26,14 @@ import Test.QuickCheck.Random (QCGen (QCGen))
 
 -- | Multiparametric Boltzmann samplers.
 class BoltzmannSampler a where
+  -- |
+  --  Samples a random object of type @a@. If the object size is larger than
+  --  the given upper bound parameter, @Nothing@ is returned instead.
   sample :: RandomGen g => Int -> MaybeT (BuffonMachine g) (a, Int)
 
+-- |
+--  Rejection sampler for type @a@. Given lower and upper bound @lb@ and @ub@
+--  generates a random objects of size on between @lb@ and @ub@.
 rejectionSampler ::
   (RandomGen g, BoltzmannSampler a) => Int -> Int -> BuffonMachine g a
 rejectionSampler lb ub = do
@@ -35,6 +46,10 @@ rejectionSampler lb ub = do
             Nothing -> rejectionSampler lb ub
         )
 
+-- |
+--  Rejection sampler for type @a@ which uses a given @eps@ parameter to
+--  determine the admissible size window @[(1-eps) N, (1+eps) N]@ for a
+--  sampler centered around the target mean size @N@.
 toleranceRejectionSampler ::
   (RandomGen g, BoltzmannSampler a) => Int -> Double -> BuffonMachine g a
 toleranceRejectionSampler n eps = rejectionSampler lb ub
@@ -42,6 +57,9 @@ toleranceRejectionSampler n eps = rejectionSampler lb ub
     lb = floor $ (1 - eps) * fromIntegral n
     ub = ceiling $ (1 + eps) * fromIntegral n
 
+-- |
+--  Hoists a given Boltzmann sampler for @a@ into
+--  a Quickcheck generator @Gen a@.
 hoistBoltzmannSampler :: BoltzmannSampler a => Gen a
 hoistBoltzmannSampler = MkGen $ \(QCGen g) n ->
   let machine = rejectionSampler 0 n

src/Data/Boltzmann.hs

@@ -8,6 +8,7 @@ module Data.Boltzmann (
   BoltzmannSampler (..),
   rejectionSampler,
   toleranceRejectionSampler,
+  hoistBoltzmannSampler,
   mkDefWeights,
   BuffonMachine,
   EvalIO (..),
@@ -28,6 +29,7 @@ import Data.Boltzmann.System.TH (
 
 import Data.Boltzmann.Sampler (
   BoltzmannSampler (..),
+  hoistBoltzmannSampler,
   rejectionSampler,
   toleranceRejectionSampler,
  )