@@ -866,21 +866,51 @@ module Prelude
866866
867867module Data.Function where
868868
869+ -- | The `on` function is used to change the domain of a binary operator.
870+ -- |
871+ -- | For example, given a function `height :: Person -> Number`, we can create a function which compares two people by height:
872+ -- |
873+ -- | ```purescript
874+ -- | taller :: (>) `on` height
875+ -- | ```
876+ -- |
869877 on :: forall a b c. (b -> b -> c) -> (a -> b) -> a -> a -> c
870878 on f g x y = g x `f` g y
871879
880+ -- | A function of zero arguments
872881 foreign import data Fn0 :: * -> *
882+
883+ -- | A function of one argument
873884 foreign import data Fn1 :: * -> * -> *
885+
886+ -- | A function of two arguments
874887 foreign import data Fn2 :: * -> * -> * -> *
888+
889+ -- | A function of three arguments
875890 foreign import data Fn3 :: * -> * -> * -> * -> *
891+
892+ -- | A function of four arguments
876893 foreign import data Fn4 :: * -> * -> * -> * -> * -> *
894+
895+ -- | A function of five arguments
877896 foreign import data Fn5 :: * -> * -> * -> * -> * -> * -> *
897+
898+ -- | A function of six arguments
878899 foreign import data Fn6 :: * -> * -> * -> * -> * -> * -> * -> *
900+
901+ -- | A function of seven arguments
879902 foreign import data Fn7 :: * -> * -> * -> * -> * -> * -> * -> * -> *
903+
904+ -- | A function of eight arguments
880905 foreign import data Fn8 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> *
906+
907+ -- | A function of nine arguments
881908 foreign import data Fn9 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *
909+
910+ -- | A function of ten arguments
882911 foreign import data Fn10 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *
883912
913+ -- | Create a function of no arguments
884914 foreign import mkFn0
885915 """
886916 function mkFn0(fn) {
@@ -890,6 +920,7 @@ module Data.Function where
890920 }
891921 """ :: forall a. (Unit -> a) -> Fn0 a
892922
923+ -- | Create a function of one argument
893924 foreign import mkFn1
894925 """
895926 function mkFn1(fn) {
@@ -899,6 +930,7 @@ module Data.Function where
899930 }
900931 """ :: forall a b. (a -> b) -> Fn1 a b
901932
933+ -- | Create a function of two arguments from a curried function
902934 foreign import mkFn2
903935 """
904936 function mkFn2(fn) {
@@ -908,6 +940,7 @@ module Data.Function where
908940 }
909941 """ :: forall a b c. (a -> b -> c) -> Fn2 a b c
910942
943+ -- | Create a function of three arguments from a curried function
911944 foreign import mkFn3
912945 """
913946 function mkFn3(fn) {
@@ -917,6 +950,7 @@ module Data.Function where
917950 }
918951 """ :: forall a b c d. (a -> b -> c -> d) -> Fn3 a b c d
919952
953+ -- | Create a function of four arguments from a curried function
920954 foreign import mkFn4
921955 """
922956 function mkFn4(fn) {
@@ -926,6 +960,7 @@ module Data.Function where
926960 }
927961 """ :: forall a b c d e. (a -> b -> c -> d -> e) -> Fn4 a b c d e
928962
963+ -- | Create a function of five arguments from a curried function
929964 foreign import mkFn5
930965 """
931966 function mkFn5(fn) {
@@ -935,6 +970,7 @@ module Data.Function where
935970 }
936971 """ :: forall a b c d e f. (a -> b -> c -> d -> e -> f) -> Fn5 a b c d e f
937972
973+ -- | Create a function of six arguments from a curried function
938974 foreign import mkFn6
939975 """
940976 function mkFn6(fn) {
@@ -944,6 +980,7 @@ module Data.Function where
944980 }
945981 """ :: forall a b c d e f g. (a -> b -> c -> d -> e -> f -> g) -> Fn6 a b c d e f g
946982
983+ -- | Create a function of seven arguments from a curried function
947984 foreign import mkFn7
948985 """
949986 function mkFn7(fn) {
@@ -953,6 +990,7 @@ module Data.Function where
953990 }
954991 """ :: forall a b c d e f g h. (a -> b -> c -> d -> e -> f -> g -> h) -> Fn7 a b c d e f g h
955992
993+ -- | Create a function of eight arguments from a curried function
956994 foreign import mkFn8
957995 """
958996 function mkFn8(fn) {
@@ -962,6 +1000,7 @@ module Data.Function where
9621000 }
9631001 """ :: forall a b c d e f g h i. (a -> b -> c -> d -> e -> f -> g -> h -> i) -> Fn8 a b c d e f g h i
9641002
1003+ -- | Create a function of nine arguments from a curried function
9651004 foreign import mkFn9
9661005 """
9671006 function mkFn9(fn) {
@@ -971,6 +1010,7 @@ module Data.Function where
9711010 }
9721011 """ :: forall a b c d e f g h i j. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j) -> Fn9 a b c d e f g h i j
9731012
1013+ -- | Create a function of ten arguments from a curried function
9741014 foreign import mkFn10
9751015 """
9761016 function mkFn10(fn) {
@@ -980,6 +1020,7 @@ module Data.Function where
9801020 }
9811021 """ :: forall a b c d e f g h i j k. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j -> k) -> Fn10 a b c d e f g h i j k
9821022
1023+ -- | Apply a function of no arguments
9831024 foreign import runFn0
9841025 """
9851026 function runFn0(fn) {
@@ -987,6 +1028,7 @@ module Data.Function where
9871028 }
9881029 """ :: forall a. Fn0 a -> a
9891030
1031+ -- | Apply a function of one argument
9901032 foreign import runFn1
9911033 """
9921034 function runFn1(fn) {
@@ -996,6 +1038,7 @@ module Data.Function where
9961038 }
9971039 """ :: forall a b. Fn1 a b -> a -> b
9981040
1041+ -- | Apply a function of two arguments
9991042 foreign import runFn2
10001043 """
10011044 function runFn2(fn) {
@@ -1007,6 +1050,7 @@ module Data.Function where
10071050 }
10081051 """ :: forall a b c. Fn2 a b c -> a -> b -> c
10091052
1053+ -- | Apply a function of three arguments
10101054 foreign import runFn3
10111055 """
10121056 function runFn3(fn) {
@@ -1020,6 +1064,7 @@ module Data.Function where
10201064 }
10211065 """ :: forall a b c d. Fn3 a b c d -> a -> b -> c -> d
10221066
1067+ -- | Apply a function of four arguments
10231068 foreign import runFn4
10241069 """
10251070 function runFn4(fn) {
@@ -1035,6 +1080,7 @@ module Data.Function where
10351080 }
10361081 """ :: forall a b c d e. Fn4 a b c d e -> a -> b -> c -> d -> e
10371082
1083+ -- | Apply a function of five arguments
10381084 foreign import runFn5
10391085 """
10401086 function runFn5(fn) {
@@ -1052,6 +1098,7 @@ module Data.Function where
10521098 }
10531099 """ :: forall a b c d e f. Fn5 a b c d e f -> a -> b -> c -> d -> e -> f
10541100
1101+ -- | Apply a function of six arguments
10551102 foreign import runFn6
10561103 """
10571104 function runFn6(fn) {
@@ -1071,6 +1118,7 @@ module Data.Function where
10711118 }
10721119 """ :: forall a b c d e f g. Fn6 a b c d e f g -> a -> b -> c -> d -> e -> f -> g
10731120
1121+ -- | Apply a function of seven arguments
10741122 foreign import runFn7
10751123 """
10761124 function runFn7(fn) {
@@ -1092,6 +1140,7 @@ module Data.Function where
10921140 }
10931141 """ :: forall a b c d e f g h. Fn7 a b c d e f g h -> a -> b -> c -> d -> e -> f -> g -> h
10941142
1143+ -- | Apply a function of eight arguments
10951144 foreign import runFn8
10961145 """
10971146 function runFn8(fn) {
@@ -1115,6 +1164,7 @@ module Data.Function where
11151164 }
11161165 """ :: forall a b c d e f g h i. Fn8 a b c d e f g h i -> a -> b -> c -> d -> e -> f -> g -> h -> i
11171166
1167+ -- | Apply a function of nine arguments
11181168 foreign import runFn9
11191169 """
11201170 function runFn9(fn) {
@@ -1140,6 +1190,7 @@ module Data.Function where
11401190 }
11411191 """ :: forall a b c d e f g h i j. Fn9 a b c d e f g h i j -> a -> b -> c -> d -> e -> f -> g -> h -> i -> j
11421192
1193+ -- | Apply a function of ten arguments
11431194 foreign import runFn10
11441195 """
11451196 function runFn10(fn) {
@@ -1169,6 +1220,9 @@ module Data.Function where
11691220
11701221module Prelude.Unsafe where
11711222
1223+ -- | Find the element of an array at the specified index.
1224+ -- |
1225+ -- | Note: this function can cause unpredictable failure at runtime if the index is out-of-bounds.
11721226 foreign import unsafeIndex
11731227 """
11741228 function unsafeIndex(xs) {
@@ -1178,8 +1232,18 @@ module Prelude.Unsafe where
11781232 }
11791233 """ :: forall a. [a] -> Number -> a
11801234
1181−module Control.Monad.Eff where
1235+module Control.Monad.Eff
1236+ ( Eff()
1237+ , Pure()
1238+ , runPure
1239+ , untilE, whileE, forE, foreachE
1240+ ) where
11821241
1242+ -- | The `Eff` type constructor is used to represent _native_ effects.
1243+ -- |
1244+ -- | See [Handling Native Effects with the Eff Monad](https://github.com/purescript/purescript/wiki/Handling-Native-Effects-with-the-Eff-Monad) for more details.
1245+ -- |
1246+ -- | The first type parameter is a row of effects which represents the contexts in which a computation can be run, and the second type parameter is the return type.
11831247 foreign import data Eff :: # ! -> * -> *
11841248
11851249 foreign import returnE
@@ -1202,8 +1266,15 @@ module Control.Monad.Eff where
12021266 }
12031267 """ :: forall e a b. Eff e a -> (a -> Eff e b) -> Eff e b
12041268
1269+ -- | The `Pure` type synonym represents _pure_ computations, i.e. ones in which all effects have been handled.
1270+ -- |
1271+ -- | The `runPure` function can be used to run pure computations and obtain their result.
12051272 type Pure a = forall e. Eff e a
12061273
1274+ -- | Run a pure computation and return its result.
1275+ -- |
1276+ -- | Note: since this function has a rank-2 type, it may cause problems to apply this function using the `$` operator. The recommended approach
1277+ -- | is to use parentheses instead.
12071278 foreign import runPure
12081279 """
12091280 function runPure(f) {
@@ -1225,6 +1296,10 @@ module Control.Monad.Eff where
12251296
12261297 instance monadEff :: Monad (Eff e)
12271298
1299+ -- | Loop until a condition becomes `true`.
1300+ -- |
1301+ -- | `untilE b` is an effectful computation which repeatedly runs the effectful computation `b`,
1302+ -- | until its return value is `true`.
12281303 foreign import untilE
12291304 """
12301305 function untilE(f) {
@@ -1235,6 +1310,10 @@ module Control.Monad.Eff where
12351310 }
12361311 """ :: forall e. Eff e Boolean -> Eff e Unit
12371312
1313+ -- | Loop while a condition is `true`.
1314+ -- |
1315+ -- | `whileE b m` is effectful computation which runs the effectful computation `b`. If its result is
1316+ -- | `true`, it runs the effectful computation `m` and loops. If not, the computation ends.
12381317 foreign import whileE
12391318 """
12401319 function whileE(f) {
@@ -1249,6 +1328,10 @@ module Control.Monad.Eff where
12491328 }
12501329 """ :: forall e a. Eff e Boolean -> Eff e a -> Eff e Unit
12511330
1331+ -- | Loop over a consecutive collection of numbers.
1332+ -- |
1333+ -- | `forE lo hi f` runs the computation returned by the function `f` for each of the inputs
1334+ -- | between `lo` (inclusive) and `hi` (exclusive).
12521335 foreign import forE
12531336 """
12541337 function forE(lo) {
@@ -1264,7 +1347,9 @@ module Control.Monad.Eff where
12641347 }
12651348 """ :: forall e. Number -> Number -> (Number -> Eff e Unit) -> Eff e Unit
12661349
1267−
1350+ -- | Loop over an array of values.
1351+ -- |
1352+ -- | `foreach xs f` runs the computation returned by the function `f` for each of the inputs `xs`.
12681353 foreign import foreachE
12691354 """
12701355 function foreachE(as) {
@@ -1282,6 +1367,9 @@ module Control.Monad.Eff.Unsafe where
12821367
12831368 import Control.Monad.Eff
12841369
1370+ -- | Change the type of an effectful computation, allowing it to be run in another context.
1371+ -- |
1372+ -- | Note: use of this function can result in arbitrary side-effects/
12851373 foreign import unsafeInterleaveEff
12861374 """
12871375 function unsafeInterleaveEff(f) {
@@ -1293,8 +1381,10 @@ module Debug.Trace where
12931381
12941382 import Control.Monad.Eff
12951383
1384+ -- | The `Trace` effect represents those computations which write to the console.
12961385 foreign import data Trace :: !
12971386
1387+ -- | Write a `String` to the console.
12981388 foreign import trace
12991389 """
13001390 function trace(s) {
@@ -1305,6 +1395,7 @@ module Debug.Trace where
13051395 }
13061396 """ :: forall r. String -> Eff (trace :: Trace | r) Unit
13071397
1398+ -- | Write a value to the console, using its `Show` instance to produce a `String`.
13081399 print :: forall a r. (Show a) => a -> Eff (trace :: Trace | r) Unit
13091400 print o = trace (show o)
13101401
@@ -1312,10 +1403,17 @@ module Control.Monad.ST where
13121403
13131404 import Control.Monad.Eff
13141405
1406+ -- | The `ST` effect represents _local mutation_, i.e. mutation which does not "escape" into the surrounding computation.
1407+ -- |
1408+ -- | An `ST` computation is parameterized by a phantom type which is used to restrict the set of reference cells it is allowed to access.
1409+ -- |
1410+ -- | The `runST` function can be used to handle the `ST` effect.
13151411 foreign import data ST :: * -> !
13161412
1413+ -- | The type `STRef s a` represents a mutable reference holding a value of type `a`, which can be used with the `ST s` effect.
13171414 foreign import data STRef :: * -> * -> *
13181415
1416+ -- | Create a new mutable reference.
13191417 foreign import newSTRef
13201418 """
13211419 function newSTRef(val) {
@@ -1325,6 +1423,7 @@ module Control.Monad.ST where
13251423 }
13261424 """ :: forall a h r. a -> Eff (st :: ST h | r) (STRef h a)
13271425
1426+ -- | Read the current value of a mutable reference.
13281427 foreign import readSTRef
13291428 """
13301429 function readSTRef(ref) {
@@ -1334,6 +1433,7 @@ module Control.Monad.ST where
13341433 }
13351434 """ :: forall a h r. STRef h a -> Eff (st :: ST h | r) a
13361435
1436+ -- | Modify the value of a mutable reference by applying a function to the current value.
13371437 foreign import modifySTRef
13381438 """
13391439 function modifySTRef(ref) {
@@ -1345,6 +1445,7 @@ module Control.Monad.ST where
13451445 }
13461446 """ :: forall a h r. STRef h a -> (a -> a) -> Eff (st :: ST h | r) a
13471447
1448+ -- | Set the value of a mutable reference.
13481449 foreign import writeSTRef
13491450 """
13501451 function writeSTRef(ref) {
@@ -1356,6 +1457,12 @@ module Control.Monad.ST where
13561457 }
13571458 """ :: forall a h r. STRef h a -> a -> Eff (st :: ST h | r) a
13581459
1460+ -- | Run an `ST` computation.
1461+ -- |
1462+ -- | Note: the type of `runST` uses a rank-2 type to constrain the phantom type `s`, such that the computation must not leak any mutable references
1463+ -- | to the surrounding computation.
1464+ -- |
1465+ -- | It may cause problems to apply this function using the `$` operator. The recommended approach is to use parentheses instead.
13591466 foreign import runST
13601467 """
13611468 function runST(f) {
@@ -1363,5 +1470,9 @@ module Control.Monad.ST where
13631470 }
13641471 """ :: forall a r. (forall h. Eff (st :: ST h | r) a) -> Eff r a
13651472
1473+ -- | A convenience function which combines `runST` with `runPure`, which can be used when the only required effect is `ST`.
1474+ -- |
1475+ -- | Note: since this function has a rank-2 type, it may cause problems to apply this function using the `$` operator. The recommended approach
1476+ -- | is to use parentheses instead.
13661477 pureST :: forall a. (forall h r. Eff (st :: ST h | r) a) -> a
13671478 pureST st = runPure (runST st)