dph-base: docs cleanup
authorBen Lippmeier <benl@ouroborus.net>
Fri, 3 Feb 2012 02:14:10 +0000 (13:14 +1100)
committerBen Lippmeier <benl@ouroborus.net>
Fri, 3 Feb 2012 02:14:10 +0000 (13:14 +1100)
dph-base/Data/Array/Parallel/Array.hs
dph-base/Data/Array/Parallel/Base.hs
dph-base/Data/Array/Parallel/Base/Config.hs
dph-base/Data/Array/Parallel/Base/Debug.hs
dph-base/Data/Array/Parallel/Base/Tag.hs [moved from dph-base/Data/Array/Parallel/Base/Util.hs with 85% similarity]
dph-base/Data/Array/Parallel/Base/Text.hs
dph-base/Data/Array/Parallel/Base/TracePrim.hs
dph-base/Data/Array/Parallel/Pretty.hs
dph-base/dph-base.cabal

index 86a7a4a..f77458c 100644 (file)
@@ -15,12 +15,25 @@ import Prelude                  hiding (length)
 
 
 class Array a e where
+ -- | Check whether an array has a valid internal representation.
  valid      :: a e -> Bool
+
+ -- | Yield an array with just a single element.
  singleton  :: e   -> a e
+
+ -- | Append two arrays.
  append     :: a e -> a e -> a e
+
+ -- | Yield the length of an array.
  length     :: a e -> Int
+
+ -- | Retrieve the element at the given index. 
  index      :: a e -> Int -> e
+
+ -- | Convert an array to a vector.
  toVector   :: a e -> Vector e
+
+ -- | Convert a vector to an array.
  fromVector :: Vector e -> a e
  
 
@@ -105,4 +118,4 @@ fromVectors3
 fromVectors3
         = fromVector . V.map fromVector . V.map (V.map fromVector)
 
-   
\ No newline at end of file
+   
index 6e20edc..e4ff587 100644 (file)
@@ -1,18 +1,11 @@
--- | Basic functionality, imported by most modules.
+-- | Common config and debugging functions. Imported by most modules.
 module Data.Array.Parallel.Base 
         ( -- * Debugging infrastructure
-          module Data.Array.Parallel.Base.Debug
-        , module Data.Array.Parallel.Base.Config
+          module Data.Array.Parallel.Base.Config
+        , module Data.Array.Parallel.Base.Debug
 
-          -- * Data constructor tags
-        , module Data.Array.Parallel.Base.Util
-
-          -- * Utils for defining Read\/Show instances.
-        , module Data.Array.Parallel.Base.Text
-
-          -- * Tracing infrastructure
-        , module Data.Array.Parallel.Base.DTrace
-        , module Data.Array.Parallel.Base.TracePrim
+          -- * Data constructor rags
+        , module Data.Array.Parallel.Base.Tag
 
           -- * ST monad re-exported from GHC
         , ST(..)
@@ -20,9 +13,6 @@ module Data.Array.Parallel.Base
 where
 import Data.Array.Parallel.Base.Debug
 import Data.Array.Parallel.Base.Config
-import Data.Array.Parallel.Base.Util
-import Data.Array.Parallel.Base.Text
-import Data.Array.Parallel.Base.DTrace
-import Data.Array.Parallel.Base.TracePrim
+import Data.Array.Parallel.Base.Tag
 import GHC.ST (ST(..), runST)
 
index e5cc111..6fea9c5 100644 (file)
@@ -1,8 +1,8 @@
 -- | Top level hard-wired configuration flags.
 --   TODO: This should be generated by the make system
 module Data.Array.Parallel.Base.Config
-        ( debug
-        , debugCritical
+        ( debugCritical
+        , debug
         , tracePrimEnabled)
 where
 
@@ -19,8 +19,8 @@ debug :: Bool
 debug                   = False
 
 
--- | Print tracing information for each DPH primitive to console.
---   The tracing hooks are in dph-prim-par/D/A/P/Unlifted.hs
+-- | Print tracing information for each flat array primitive to console.
+--   The tracing hooks are in `dph-prim-par:Data.Array.Parallel.Unlifted`
 tracePrimEnabled        :: Bool
 tracePrimEnabled        = False
 
index 0071e3b..cfc9708 100644 (file)
@@ -82,7 +82,7 @@ checkLen loc n i v
 
 -- | Slice check, enable when `debug` = `True`.
 --
---   The vector must contain at least sliceStart + sliceLen elements.
+--   The vector must contain at least `sliceStart` + `sliceLen` elements.
 -- 
 checkSlice :: String -> Int -> Int -> Int -> a -> a
 checkSlice loc vecLen sliceStart sliceLen v
similarity index 85%
rename from dph-base/Data/Array/Parallel/Base/Util.hs
rename to dph-base/Data/Array/Parallel/Base/Tag.hs
index 5a098f0..0d5d20f 100644 (file)
@@ -1,9 +1,9 @@
 
--- | Constructor tags.
-module Data.Array.Parallel.Base.Util 
+-- | Data constructor tags.
+module Data.Array.Parallel.Base.Tag 
         ( Tag
-        , fromBool, toBool
-        , tagToInt, intToTag)
+        , tagToInt, intToTag
+        , fromBool, toBool)
 where
 
 
@@ -12,6 +12,18 @@ where
 type Tag = Int
 
 
+-- | Convert a `Tag` to an `Int`. This is identity at the value level.
+tagToInt :: Tag -> Int
+tagToInt = id
+{-# INLINE tagToInt #-}
+
+
+-- | Convert an `Int` to a `Tag`. This is identity at the value level.
+intToTag :: Int -> Tag
+intToTag = id
+{-# INLINE intToTag #-}
+
+
 -- | Get the `Tag` of a `Bool` value. `False` is 0, `True` is 1.
 fromBool :: Bool -> Tag
 fromBool False = 0
@@ -26,14 +38,4 @@ toBool n | n == 0    = False
 {-# INLINE toBool #-}
 
 
--- | Convert a `Tag` to an `Int`. This is identity at the value level.
-tagToInt :: Tag -> Int
-tagToInt = id
-{-# INLINE tagToInt #-}
-
-
--- | Convert an `Int` to a `Tag`. This is identity at the value level.
-intToTag :: Int -> Tag
-intToTag = id
-{-# INLINE intToTag #-}
 
index cbfb5b3..75e1d1a 100644 (file)
@@ -7,16 +7,18 @@ module Data.Array.Parallel.Base.Text
 where
 import Text.Read
 
+
 showsApp :: Show a => Int -> String -> a -> ShowS
-showsApp k fn arg = showParen (k>10) 
-                    (showString fn . showChar ' ' . showsPrec 11 arg)
+showsApp k fn arg 
+        = showParen (k>10) 
+          (showString fn . showChar ' ' . showsPrec 11 arg)
 
 readApp :: Read a => String -> ReadPrec a
-readApp fn = parens (prec 10 $
-  do
-    Ident ide <- lexP
-    if ide /= fn then pfail else step readPrec
-  )
+readApp fn 
+ = parens $ prec 10 
$ do   Ident ide <- lexP
+        if ide /= fn then pfail else step readPrec
+
 
 readsApp :: Read a => Int -> String -> ReadS a
 readsApp k fn = readPrec_to_S (readApp fn) k
index 533fbcf..f087d13 100644 (file)
@@ -1,5 +1,5 @@
--- | When `tracePrimEnabled` in "Data.Array.Parallel.Config" is @True@, DPH programs will print
---   out what array primitives they're using at runtime. See `tracePrim` for details.
+-- | When `tracePrimEnabled`, DPH programs will print out what flat array
+--   primitives they're using at runtime. See `tracePrim` for details.
 module Data.Array.Parallel.Base.TracePrim
         ( tracePrim
         , TracePrim(..))
@@ -7,12 +7,13 @@ where
 import Data.Array.Parallel.Base.Config
 import qualified Debug.Trace
 
+
 -- | Print tracing information to console.
 --
 --    This function is used to wrap the calls to DPH primitives defined
 --    in @dph-prim-par@:"Data.Array.Parallel.Unlifted"
 --
---    Tracing is only enabled when `tracePrimEnabled` in "Data.Array.Parallel.Base.Config"  is `True`,
+--    Tracing is only enabled when `tracePrimEnabled` is `True`.
 --    otherwise it's a no-op.
 --   
 tracePrim :: TracePrim -> a -> a
@@ -21,10 +22,13 @@ tracePrim tr x
  | otherwise            = x
  
 
--- | Records information about the use of a primitive operator.
+-- | Records information about the use of a flat array primitive.
 --
 --    These are the operator names that the vectoriser introduces.
---    The actual implementation of each operator varies depending on what DPH backend we're using.
+--
+--    The actual implementation of each operator varies depending on what
+--    DPH primitive library is being used.
+--
 --    We only trace operators that are at least O(n) in complexity. 
 data TracePrim
         = TraceReplicate   { traceCount      :: Int}
index a3934b7..77a3730 100644 (file)
@@ -10,7 +10,7 @@ import qualified Data.Vector            as V
 import Data.Vector                      (Vector)
 
 
--- | Pretty print physical structure of data.
+-- | Pretty print the physical structure of data.
 class PprPhysical a where
  pprp :: a -> Doc
 
index c4ce113..757e873 100644 (file)
@@ -7,7 +7,7 @@ Maintainer:     Ben Lippmeier <benl@cse.unsw.edu.au>
 Homepage:       http://www.haskell.org/haskellwiki/GHC/Data_Parallel_Haskell
 Category:       Data Structures
 Synopsis:       Data Parallel Haskell common config and debugging functions.
-Description:    Data Parallel Haskell common config and debugging functions.
+Description:    Common configuration, debugging and utilities.
 
 
 Cabal-Version:  >= 1.6
@@ -20,18 +20,18 @@ Flag DTrace
 Library
   Exposed-Modules:
         Data.Array.Parallel.Base
+        Data.Array.Parallel.Base.Text
+        Data.Array.Parallel.Base.DTrace
+        Data.Array.Parallel.Base.TracePrim
         Data.Array.Parallel.Stream
         Data.Array.Parallel.Pretty
         Data.Array.Parallel.Array
-        Data.Array.Parallel.Base.DTrace
-        Data.Array.Parallel.Base.TracePrim
 
   Other-Modules:
         Data.Array.Parallel.Base.Config
         Data.Array.Parallel.Base.Debug
-        Data.Array.Parallel.Base.Util
-        Data.Array.Parallel.Base.Text
-
+        Data.Array.Parallel.Base.Tag
+        
   Include-Dirs:
         include