Add Random documentation.

Author: dmjio

src/ArrayFire/Random.hs

@@ -22,7 +22,7 @@ module ArrayFire.Random
   ( createRandomEngine
   , retainRandomEngine
   , setRandomEngine
-  , getRandomEngine
+  , getRandomEngineType
   , randomEngineSetSeed
   , getDefaultRandomEngine
   , setDefaultRandomEngineType
@@ -49,10 +49,14 @@ import ArrayFire.Internal.Defines
 import ArrayFire.Internal.Random
 import ArrayFire.FFI
 
+-- | Create random number generator object.
 createRandomEngine
   :: Int
+  -- ^ Initial seed value of random number generator
   -> RandomEngineType
+  -- ^ Type of random engine to employ
   -> IO RandomEngine
+  -- ^ Opaque RandomEngine handle
 createRandomEngine (fromIntegral -> n) typ =
   mask_ $ do
     ptr <-
@@ -62,39 +66,52 @@ createRandomEngine (fromIntegral -> n) typ =
     fptr <- newForeignPtr af_release_random_engine_finalizer ptr
     pure (RandomEngine fptr)
 
+-- | Retains 'RandomEngine' reference
 retainRandomEngine
   :: RandomEngine
+  -- ^ 'RandomEngine' to retain
   -> IO RandomEngine
+  -- ^ Retained 'RandomEngine'
 retainRandomEngine =
   (`op1re` af_retain_random_engine)
 
 foreign import ccall unsafe "af_random_engine_set_type_"
   af_random_engine_set_type_ :: AFRandomEngine -> AFRandomEngineType -> IO AFErr
 
+-- | Sets RandomEngine to a new 'RandomEngineType'
 setRandomEngine
   :: RandomEngine
+  -- ^ 'RandomEngine' as input
   -> RandomEngineType
+  -- ^ 'RandomEngineType' to set 'RandomEngine' to
   -> IO ()
 setRandomEngine r t =
   r `inPlaceEng` (`af_random_engine_set_type_` (fromRandomEngine t))
 
-getRandomEngine
+-- | Retrieves 'RandomEngine'
+getRandomEngineType
   :: RandomEngine
+  -- ^ 'RandomEngine' argument
   -> IO RandomEngineType
-getRandomEngine r =
+  -- ^ 'RandomEngineType' returned
+getRandomEngineType r =
   toRandomEngine <$>
     r `infoFromRandomEngine` af_random_engine_get_type
 
 foreign import ccall unsafe "af_random_engine_set_seed_"
   af_random_engine_set_seed_ :: AFRandomEngine -> IntL -> IO AFErr
 
+-- | Sets seed on 'RandomEngine'
 randomEngineSetSeed
   :: RandomEngine
+  -- ^ 'RandomEngine' argument
   -> Int
+  -- ^ Seed
   -> IO ()
 randomEngineSetSeed r t =
   r `inPlaceEng` (`af_random_engine_set_seed_` (fromIntegral t))
 
+-- | Retrieve default 'RandomEngine'
 getDefaultRandomEngine
   :: IO RandomEngine
 getDefaultRandomEngine =
@@ -106,22 +123,28 @@ getDefaultRandomEngine =
     fptr <- newForeignPtr af_release_random_engine_finalizer ptr
     pure (RandomEngine fptr)
 
+-- | Set defualt 'RandomEngine' type
 setDefaultRandomEngineType
   :: RandomEngineType
+  -- ^ 'RandomEngine' type
   -> IO ()
 setDefaultRandomEngineType n =
   afCall (af_set_default_random_engine_type (fromRandomEngine n))
 
+-- | Retrieve seed of 'RandomEngine'
 randomEngineGetSeed
   :: RandomEngine
+  -- ^ RandomEngine argument
   -> IO Int
 randomEngineGetSeed r =
   fromIntegral <$>
     r `infoFromRandomEngine` af_random_engine_get_seed
 
+-- | Set random seed
 setSeed :: Int -> IO ()
 setSeed = afCall . af_set_seed . fromIntegral
 
+-- | Retrieve random seed
 getSeed :: IO Int
 getSeed = fromIntegral <$> afCall1 af_get_seed
 
@@ -145,9 +168,11 @@ randEng dims f (RandomEngine fptr) = mask_ $
     n = fromIntegral (length dims)
     typ = afType (Proxy @ a)
 
+-- | Generate random 'Array'
 rand
   :: forall a . AFType a
   => [Int]
+  -- ^ Dimensions
   -> (Ptr AFArray -> CUInt -> Ptr DimT -> AFDtype -> IO AFErr)
   -> IO (Array a)
 rand dims f = mask_ $ do
@@ -163,32 +188,42 @@ rand dims f = mask_ $ do
         n = fromIntegral (length dims)
         typ = afType (Proxy @ a)
 
+-- | Generate random 'Array'
 randn
   :: forall a
    . AFType a
   => [Int]
+  -- ^ Dimensions of random array
   -> IO (Array a)
 randn dims = rand @a dims af_randn
 
+-- | Generate random uniform 'Array'
 randu
   :: forall a . AFType a
   => [Int]
+  -- ^ Dimensions of random array
   -> IO (Array a)
 randu dims = rand @a dims af_randu
 
+-- | Generate random 'Array' from uniform distribution
 randomUniform
   :: forall a . AFType a
   => [Int]
+  -- ^ Dimensions of random array
   -> RandomEngine
+  -- ^ 'RandomEngine' argument
   -> IO (Array a)
 randomUniform dims eng =
   randEng @a dims af_random_uniform eng
 
+-- | Generate random 'Array' from normal distribution
 randomNormal
   :: forall a
    . AFType a
   => [Int]
+  -- ^ Dimensions of random array
   -> RandomEngine
+  -- ^ 'RandomEngine' argument
   -> IO (Array a)
 randomNormal dims eng =
   randEng @a dims af_random_normal eng

test/ArrayFire/FeaturesSpec.hs

@@ -2,7 +2,6 @@
 module ArrayFire.FeaturesSpec where
 
 import ArrayFire
-
 import Test.Hspec
 
 spec :: Spec

test/ArrayFire/RandomSpec.hs

@@ -11,18 +11,18 @@ spec =
   describe "Random engine spec" $ do
     it "Should create random engine" $ do
       (`shouldBe` Philox)
-         =<< getRandomEngine
+         =<< getRandomEngineType
          =<< createRandomEngine 5000 Philox
       (`shouldBe` Mersenne)
-         =<< getRandomEngine
+         =<< getRandomEngineType
          =<< createRandomEngine 5000 Mersenne
       (`shouldBe` ThreeFry)
-         =<< getRandomEngine
+         =<< getRandomEngineType
          =<< createRandomEngine 5000 ThreeFry
     it "Should set random engine" $ do
        r <- createRandomEngine 5000 ThreeFry
        setRandomEngine r Philox
-       (`shouldBe` Philox) =<< getRandomEngine r
+       (`shouldBe` Philox) =<< getRandomEngineType r
     it "Should set and get seed" $ do
        setSeed 100
        (`shouldBe` 100) =<< getSeed