Update docs (#31)

See also #23, #29

I thought about this a bit more, and I think the reasoning for why refs
are effectful is more persuasive when viewed through the lens of purity
rather than of referential transparency, so I've updated the docs
accordingly.

I am reluctant to include code examples illustrating why Refs are
effectful here, because I think people may skim the page looking for
code examples, and in the absence of code examples which describe the
real API, I think code examples which illustrate a hypothetical version
of the API which doesn't actually exist may do more harm than good.

I am also leaning towards not including @natefaubion's example (where
you can violate the type system by defining a reference with a
polymorphic type and specializing it after the fact), since it's hard to
illustrate without a code example, and I think it's unlikely to be
useful to most people who just want to make use of the Ref API, which is
the group I think we should be considering to be our target audience
here.

Author: hdgarrood

src/Effect/Ref.purs

@@ -1,6 +1,23 @@
--- | This module defines actions for working with mutable value references.
+-- | This module defines the `Ref` type for mutable value references, as well
+-- | as actions for working with them.
 -- |
--- | _Note_: `Control.Monad.ST` provides a _safe_ alternative to `Ref` when
+-- | You'll notice that all of the functions that operate on a `Ref` (e.g.
+-- | `new`, `read`, `write`) return their result wrapped in an `Effect`.
+-- | Working with mutable references is considered effectful in PureScript
+-- | because of the principle of purity: functions should not have side
+-- | effects, and should return the same result when called with the same
+-- | arguments. If a `Ref` could be written to without using `Effect`, that
+-- | would cause a side effect (the effect of changing the result of subsequent
+-- | reads for that `Ref`). If there were a function for reading the current
+-- | value of a `Ref` without the result being wrapped in `Effect`, the result
+-- | of calling that function would change each time a new value was written to
+-- | the `Ref`. Even creating a new `Ref` is effectful: if there were a
+-- | function for creating a new `Ref` with the type `forall s. s -> Ref s`,
+-- | then calling that function twice with the same argument would not give the
+-- | same result in each case, since you'd end up with two distinct references
+-- | which could be updated independently of each other.
+-- |
+-- | _Note_: `Control.Monad.ST` provides a pure alternative to `Ref` when
 -- | mutation is restricted to a local scope.
 module Effect.Ref
   ( Ref
@@ -25,7 +42,7 @@ type role Ref representational
 -- | Create a new mutable reference containing the specified value.
 foreign import new :: forall s. s -> Effect (Ref s)
 
--- | Read the current value of a mutable reference
+-- | Read the current value of a mutable reference.
 foreign import read :: forall s. Ref s -> Effect s
 
 -- | Update the value of a mutable reference by applying a function
@@ -40,6 +57,7 @@ foreign import modifyImpl :: forall s b. (s -> { state :: s, value :: b }) -> Re
 modify :: forall s. (s -> s) -> Ref s -> Effect s
 modify f = modify' \s -> let s' = f s in { state: s', value: s' }
 
+-- | A version of `modify` which does not return the updated value.
 modify_ :: forall s. (s -> s) -> Ref s -> Effect Unit
 modify_ f s = void $ modify f s