Merge pull request #108 from idontgetoutmuch/random-clarify-rebase

Clarify docs for Random, Uniform, UniformRange

System/Random.hs

@@ -117,14 +117,12 @@ genByteString :: RandomGen g => Int -> g -> (ByteString, g)
 genByteString n g = runPureGenST g (uniformByteString n)
 {-# INLINE genByteString #-}
 
-
-{- |
-With a source of pseudo-random number supply in hand, the 'Random' class allows
-the programmer to extract pseudo-random values of a variety of types.
-
-Minimal complete definition: 'randomR' and 'random'.
-
--}
+-- | The class of types for which uniformly distributed values can be
+-- generated.
+--
+-- 'Random' exists primarily for backwards compatibility with version 1.1 of
+-- this library. In new code, use the better specified 'Uniform' and
+-- 'UniformRange' instead.
 {-# DEPRECATED randomRIO "In favor of `uniformRM`" #-}
 {-# DEPRECATED randomIO "In favor of `uniformRM`" #-}
 class Random a where
@@ -386,18 +384,18 @@ getStdRandom f = atomicModifyIORef' theStdGen (swap . f)
 --     implement word-based methods instead. See below for more information
 --     about how to write a 'RandomGen' instance.
 --
--- *   This library provides instances for 'Random' for some unbounded datatypes
---     for backwards compatibility. For an unbounded datatype, there is no way
+-- *   This library provides instances for 'Random' for some unbounded types
+--     for backwards compatibility. For an unbounded type, there is no way
 --     to generate a value with uniform probability out of its entire domain, so
---     the 'random' implementation for unbounded datatypes actually generates a
+--     the 'random' implementation for unbounded types actually generates a
 --     value based on some fixed range.
 --
 --     For 'Integer', 'random' generates a value in the 'Int' range. For 'Float'
 --     and 'Double', 'random' generates a floating point value in the range @[0,
 --     1)@.
 --
 --     This library does not provide 'Uniform' instances for any unbounded
---     datatypes.
+--     types.
 --
 -- $reproducibility
 --

System/Random/Internal.hs

@@ -420,27 +420,41 @@ instance RandomGen SM32.SMGen where
 mkStdGen :: Int -> StdGen
 mkStdGen s = SM.mkSMGen $ fromIntegral s
 
--- | Generates a value uniformly distributed over all possible values of that
--- datatype.
+-- | The class of types for which a uniformly distributed value can be drawn
+-- from all possible values of the type.
 --
 -- @since 1.2
 class Uniform a where
+  -- | Generates a value uniformly distributed over all possible values of that
+  -- type.
+  --
+  -- @since 1.2
   uniformM :: MonadRandom g s m => g s -> m a
 
--- | Generates a value uniformly distributed over the provided inclusive range.
---
--- For example, @uniformR (1,4)@ should generate values uniformly from the set
--- @[1,2,3,4]@.
---
--- The API uses an inclusive range so any range can be expressed, even when
--- using fixed-size ints, enumerations etc.
---
--- The following law should hold to make the function always defined:
---
--- > uniformRM (a,b) = uniformM (b,a)
+-- | The class of types for which a uniformly distributed value can be drawn
+-- from a range.
 --
 -- @since 1.2
 class UniformRange a where
+  -- | Generates a value uniformly distributed over the provided range.
+  --
+  -- *   For /integral types/, the range is interpreted as inclusive in the
+  --     lower and upper bound.
+  --
+  --     As an example, @uniformR (1 :: Int, 4 :: Int)@ should generate values
+  --     uniformly from the set \(\{1,2,3,4\}\).
+  --
+  -- *   For /non-integral types/, the range is interpreted as inclusive in the
+  --     lower bound and exclusive in the upper bound.
+  --
+  --     As an example, @uniformR (1 :: Float, 4 :: Float)@ should generate
+  --     values uniformly from the set \(\{x\;|\;1 \le x \lt 4\}\).
+  --
+  -- The following law should hold to make the function always defined:
+  --
+  -- > uniformRM (a, b) = uniformRM (b, a)
+  --
+  -- @since 1.2<Paste>
   uniformRM :: MonadRandom g s m => (a, a) -> g s -> m a
 
 instance UniformRange Integer where

System/Random/Monad.hs

@@ -96,16 +96,16 @@ import System.Random.Internal
 --     'RandomGen' instance into a 'MonadRandom' instance.
 --
 -- [Drawing from a range] 'UniformRange' is used to generate a value of a
---     datatype uniformly within an inclusive range.
+--     type uniformly within a range.
 --
 --     This library provides instances of 'UniformRange' for many common
---     numeric datatypes.
+--     numeric types.
 --
 -- [Drawing from the entire domain of a type] 'Uniform' is used to generate a
---     value of a datatype uniformly over all possible values of that datatype.
+--     value of a type uniformly over all possible values of that type.
 --
 --     This library provides instances of 'Uniform' for many common bounded
---     numeric datatypes.
+--     numeric types.
 --
 -- $usagemonadic
 --
@@ -387,12 +387,13 @@ runSTGen_ g action = fst $ runSTGen g action
 
 
 -- $uniform
+--
 -- This library provides two type classes to generate pseudo-random values:
 --
--- *   'UniformRange' is used to generate a value of a datatype uniformly
---     within an inclusive range.
--- *   'Uniform' is used to generate a value of a datatype uniformly over all
---     possible values of that datatype.
+-- *   'UniformRange' is used to generate a value of a type uniformly within a
+--     range.
+-- *   'Uniform' is used to generate a value of a type uniformly over all
+--     possible values of that type.
 --
 -- Types may have instances for both or just one of 'UniformRange' and
 -- 'Uniform'. A few examples illustrate this: