Docs

Author: paf31

Gruntfile.js

@@ -13,7 +13,7 @@ module.exports = function(grunt) {
 
     pscMake: ["<%=libFiles%>"],
     dotPsci: ["<%=libFiles%>"],
-    docgen: {
+    pscDocs: {
         readme: {
             src: "src/**/*.purs",
             dest: "README.md"
@@ -25,6 +25,6 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks("grunt-contrib-clean");
   grunt.loadNpmTasks("grunt-purescript");
 
-  grunt.registerTask("make", ["pscMake", "dotPsci", "docgen"]);
+  grunt.registerTask("make", ["pscMake", "dotPsci", "pscDocs"]);
   grunt.registerTask("default", ["make"]);
 };

README.md

@@ -2,28 +2,88 @@
 
 ## Module Control.Monad.Eff.Ref
 
-### Types
 
-    data Ref :: !
+This module defines an effect and actions for working with
+global mutable variables.
 
-    data RefVal :: * -> *
+_Note_: The `Control.Monad.ST` provides a _safe_ alternative
+to global mutable variables when mutation is restricted to a
+local scope.
 
+#### `Ref`
 
-### Values
+``` purescript
+data Ref :: !
+```
 
-    modifyRef :: forall s r. RefVal s -> (s -> s) -> Eff (ref :: Ref | r) Unit
+The effect associated with the use of global mutable variables.
 
-    modifyRef' :: forall s b r. RefVal s -> (s -> { retVal :: b, newState :: s }) -> Eff (ref :: Ref | r) b
+#### `RefVal`
 
-    newRef :: forall s r. s -> Eff (ref :: Ref | r) (RefVal s)
+``` purescript
+data RefVal :: * -> *
+```
 
-    readRef :: forall s r. RefVal s -> Eff (ref :: Ref | r) s
+A value of type `RefVal a` represents a mutable reference
+which holds a value of type `a`.
 
-    writeRef :: forall s r. RefVal s -> s -> Eff (ref :: Ref | r) Unit
+#### `newRef`
+
+``` purescript
+newRef :: forall s r. s -> Eff (ref :: Ref | r) (RefVal s)
+```
+
+Create a new mutable reference containing the specified value.
+
+#### `readRef`
+
+``` purescript
+readRef :: forall s r. RefVal s -> Eff (ref :: Ref | r) s
+```
+
+Read the current value of a mutable reference
+
+#### `modifyRef'`
+
+``` purescript
+modifyRef' :: forall s b r. RefVal s -> (s -> { retVal :: b, newState :: s }) -> Eff (ref :: Ref | r) b
+```
+
+Update the value of a mutable reference by applying a function
+to the current value.
+
+#### `modifyRef`
+
+``` purescript
+modifyRef :: forall s r. RefVal s -> (s -> s) -> Eff (ref :: Ref | r) Unit
+```
+
+Update the value of a mutable reference by applying a function
+to the current value.
+
+#### `writeRef`
+
+``` purescript
+writeRef :: forall s r. RefVal s -> s -> Eff (ref :: Ref | r) Unit
+```
+
+Update the value of a mutable reference to the specified value.
 
 
 ## Module Control.Monad.Eff.Ref.Unsafe
 
-### Values
 
-    unsafeRunRef :: forall eff a. Eff (ref :: Ref | eff) a -> Eff eff a
+Unsafe functions for working with mutable references.
+
+#### `unsafeRunRef`
+
+``` purescript
+unsafeRunRef :: forall eff a. Eff (ref :: Ref | eff) a -> Eff eff a
+```
+
+This handler function unsafely removes the `Ref` effect from an
+effectful action.
+
+This function might be used when it is impossible to prove to the
+typechecker that a particular mutable reference does not escape
+its scope.

package.json

@@ -2,7 +2,7 @@
   "private": true,
   "dependencies": {
     "grunt": "~0.4.4",
-    "grunt-purescript": "~0.5.1",
+    "grunt-purescript": "~0.6.0",
     "grunt-contrib-clean": "~0.5.0"
   }
 }

src/Control/Monad/Eff/Ref.purs

@@ -1,11 +1,22 @@
+-- | This module defines an effect and actions for working with
+-- | global mutable variables.
+-- |
+-- | _Note_: The `Control.Monad.ST` provides a _safe_ alternative
+-- | to global mutable variables when mutation is restricted to a
+-- | local scope.
+
 module Control.Monad.Eff.Ref where
 
 import Control.Monad.Eff
 
+-- | The effect associated with the use of global mutable variables.
 foreign import data Ref :: !
 
+-- | A value of type `RefVal a` represents a mutable reference
+-- | which holds a value of type `a`.
 foreign import data RefVal :: * -> *
 
+-- | Create a new mutable reference containing the specified value.
 foreign import newRef """
   function newRef(val) {
     return function () {
@@ -14,6 +25,7 @@ foreign import newRef """
   }
 """ :: forall s r. s -> Eff (ref :: Ref | r) (RefVal s)
 
+-- | Read the current value of a mutable reference
 foreign import readRef """
   function readRef(ref) {
     return function() {
@@ -22,7 +34,8 @@ foreign import readRef """
   }
 """ :: forall s r. RefVal s -> Eff (ref :: Ref | r) s
 
-
+-- | Update the value of a mutable reference by applying a function
+-- | to the current value.
 foreign import modifyRef' """
   function modifyRef$prime(ref) {
     return function(f) {
@@ -35,9 +48,12 @@ foreign import modifyRef' """
   }
 """ :: forall s b r. RefVal s -> (s -> {newState :: s, retVal :: b}) -> Eff (ref :: Ref | r) b
 
+-- | Update the value of a mutable reference by applying a function
+-- | to the current value.
 modifyRef :: forall s r. RefVal s -> (s -> s) -> Eff (ref :: Ref | r) Unit
 modifyRef ref f = modifyRef' ref (\s -> {newState: f s, retVal: unit})
 
+-- | Update the value of a mutable reference to the specified value.
 foreign import writeRef """
   function writeRef(ref) {
     return function(val) {

src/Control/Monad/Eff/Ref/Unsafe.purs

@@ -1,8 +1,16 @@
+-- | Unsafe functions for working with mutable references.
+
 module Control.Monad.Eff.Ref.Unsafe where
 
 import Control.Monad.Eff
 import Control.Monad.Eff.Ref
 
+-- | This handler function unsafely removes the `Ref` effect from an
+-- | effectful action.
+-- |
+-- | This function might be used when it is impossible to prove to the
+-- | typechecker that a particular mutable reference does not escape
+-- | its scope.
 foreign import unsafeRunRef 
   "function unsafeRunRef(f) {\
   \  return f;\