vectoriser: comments only

diff --git a/compiler/vectorise/Vectorise/Utils.hs b/compiler/vectorise/Vectorise/Utils.hs
index 3dd5425..8f1d7db 100644 (file)
--- a/compiler/vectorise/Vectorise/Utils.hs
+++ b/compiler/vectorise/Vectorise/Utils.hs
@@ -63,22 +63,59 @@ isAnnTypeArg (_, AnnType _) = True
 isAnnTypeArg _              = False
 
 
--- PD Functions ---------------------------------------------------------------
-replicatePD :: CoreExpr -> CoreExpr -> VM CoreExpr
-replicatePD len x = liftM (`mkApps` [len,x])
-                          (paMethod replicatePDVar "replicatePD" (exprType x))
-
+-- PD "Parallel Data" Functions -----------------------------------------------
+--
+--   Given some data that has a PA dictionary, we can convert it to its 
+--   representation type, perform some operation on the data, then convert it back.
+--
+--   In the DPH backend, the types of these functions are defined
+--   in dph-common/D.A.P.Lifted/PArray.hs
+--
+
+-- | An empty array of the given type.
 emptyPD :: Type -> VM CoreExpr
 emptyPD = paMethod emptyPDVar "emptyPD"
 
 
-packByTagPD :: Type -> CoreExpr -> CoreExpr -> CoreExpr -> CoreExpr -> VM CoreExpr
+-- | Produce an array containing copies of a given element.
+replicatePD
+       :: CoreExpr     -- ^ Number of copies in the resulting array.
+       -> CoreExpr     -- ^ Value to replicate.
+       -> VM CoreExpr
+
+replicatePD len x 
+       = liftM (`mkApps` [len,x])
+        $ paMethod replicatePDVar "replicatePD" (exprType x)
+
+
+-- | Select some elements from an array that correspond to a particular tag value
+---  and pack them into a new array.
+--   eg  packByTagPD Int# [:23, 42, 95, 50, 27, 49:]  3 [:1, 2, 1, 2, 3, 2:] 2 
+--          ==> [:42, 50, 49:]
+--
+packByTagPD 
+       :: Type         -- ^ Element type.
+       -> CoreExpr     -- ^ Source array.
+       -> CoreExpr     -- ^ Length of resulting array.
+       -> CoreExpr     -- ^ Tag values of elements in source array.
+       -> CoreExpr     -- ^ The tag value for the elements to select.
+       -> VM CoreExpr
+
 packByTagPD ty xs len tags t
   = liftM (`mkApps` [xs, len, tags, t])
           (paMethod packByTagPDVar "packByTagPD" ty)
 
 
-combinePD :: Type -> CoreExpr -> CoreExpr -> [CoreExpr] -> VM CoreExpr
+-- | Combine some arrays based on a selector.
+--     The selector says which source array to choose for each element of the
+--     resulting array.
+combinePD 
+       :: Type         -- ^ Element type
+       -> CoreExpr     -- ^ Length of resulting array
+       -> CoreExpr     -- ^ Selector.
+       -> [CoreExpr]   -- ^ Arrays to combine.
+       -> VM CoreExpr
+
 combinePD ty len sel xs
   = liftM (`mkApps` (len : sel : xs))
           (paMethod (combinePDVar n) ("combine" ++ show n ++ "PD") ty)