Restructured readme from new psc-docs

Author: garyb

README.md

@@ -2,8 +2,6 @@
 
 ## Module Data.Maybe
 
-### Types
-
 #### `Maybe`
 
 The `Maybe` type is used to represent optional values and can be seen as
@@ -14,54 +12,60 @@ is the non-null value `x`.
       = Nothing 
       | Just a
 
+#### `maybe`
 
-### Type Class Instances
+Takes a default value, a function, and a `Maybe` value. If the `Maybe`
+value is `Nothing` the default value is returned, otherwise the function
+is applied to the value inside the `Just` and the result is returned.
 
-#### `altMaybe`
+``` purescript
+maybe default f Nothing == default
+maybe default f (Just x) == f x
+```
 
-The `Alt` instance allows for a choice to be made between two `Maybe`
-values with the `<|>` operator, where the first `Just` encountered
-is taken.
+    maybe :: forall a b. b -> (a -> b) -> Maybe a -> b
+
+#### `fromMaybe`
+
+Takes a default value, and a `Maybe` value. If the `Maybe` value is
+`Nothing` the default value is returned, otherwise the value inside the
+`Just` is returned.
 
 ``` purescript
-Just x <|> Just y == Just x
-Nothing <|> Just y == Just y
-Nothing <|> Nothing == Nothing
+fromMaybe default Nothing == default
+fromMaybe default (Just x) == x
 ```
 
-    instance altMaybe :: Alt Maybe
+    fromMaybe :: forall a. a -> Maybe a -> a
 
-#### `alternativeMaybe`
+#### `isJust`
 
-The `Alternative` instance guarantees that there are both `Applicative` and
-`Plus` instances for `Maybe`.
+Returns `true` when the `Maybe` value was constructed with `Just`.
 
-    instance alternativeMaybe :: Alternative Maybe
+    isJust :: forall a. Maybe a -> Boolean
 
-#### `applicativeMaybe`
+#### `isNothing`
 
-The `Applicative` instance enables lifting of values into `Maybe` with the
-`pure` or `return` function (`return` is an alias for `pure`):
+Returns `true` when the `Maybe` value is `Nothing`.
+
+    isNothing :: forall a. Maybe a -> Boolean
+
+#### `functorMaybe`
+
+The `Functor` instance allows functions to transform the contents of a
+`Just` with the `<$>` operator:
 
 ``` purescript
-pure x :: Maybe _ == Just x
-return x :: Maybe _ == Just x
+f <$> Just x == Just (f x)
 ```
 
-Combining `Functor`'s' `<$>` with `Apply`'s `<*>` and `Applicative`'s
-`pure` can be used to pass a mixture of `Maybe` and non-`Maybe` typed
-values to a function that does not usually expect them, by using `pure`
-for any value that is not already `Maybe` typed:
+`Nothing` values are left untouched:
 
 ``` purescript
-f <$> Just x <*> pure y == Just (f x y)
+f <$> Nothing == Nothing
 ```
 
-Even though `pure = Just` it is recommended to use `pure` in situations
-like this as it allows the choice of `Applicative` to be changed later
-without having to go through and replace `Just` with a new constructor.
-
-    instance applicativeMaybe :: Applicative Maybe
+    instance functorMaybe :: Functor Maybe
 
 #### `applyMaybe`
 
@@ -99,55 +103,73 @@ f <$> Nothing <*> Nothing == Nothing
 
     instance applyMaybe :: Apply Maybe
 
-#### `bindMaybe`
+#### `applicativeMaybe`
 
-The `Bind` instance allows sequencing of `Maybe` values and functions that
-return a `Maybe` by using the `>>=` operator:
+The `Applicative` instance enables lifting of values into `Maybe` with the
+`pure` or `return` function (`return` is an alias for `pure`):
 
 ``` purescript
-Just x >>= f = f x
-Nothing >>= f = Nothing
+pure x :: Maybe _ == Just x
+return x :: Maybe _ == Just x
 ```
 
-    instance bindMaybe :: Bind Maybe
+Combining `Functor`'s' `<$>` with `Apply`'s `<*>` and `Applicative`'s
+`pure` can be used to pass a mixture of `Maybe` and non-`Maybe` typed
+values to a function that does not usually expect them, by using `pure`
+for any value that is not already `Maybe` typed:
 
-#### `eqMaybe`
+``` purescript
+f <$> Just x <*> pure y == Just (f x y)
+```
 
-The `Eq` instance allows `Maybe` values to be checked for equality with
-`==` and inequality with `/=` whenever there is an `Eq` instance for the
-type the `Maybe` contains.
+Even though `pure = Just` it is recommended to use `pure` in situations
+like this as it allows the choice of `Applicative` to be changed later
+without having to go through and replace `Just` with a new constructor.
 
-    instance eqMaybe :: (Eq a) => Eq (Maybe a)
+    instance applicativeMaybe :: Applicative Maybe
 
-#### `extendMaybe`
+#### `altMaybe`
 
-The `Extend` instance allows sequencing of `Maybe` values and functions
-that accept a `Maybe a` and return a non-`Maybe` result using the
-`<<=` operator.
+The `Alt` instance allows for a choice to be made between two `Maybe`
+values with the `<|>` operator, where the first `Just` encountered
+is taken.
 
 ``` purescript
-f <<= Nothing = Nothing
-f <<= Just x = Just (f x)
+Just x <|> Just y == Just x
+Nothing <|> Just y == Just y
+Nothing <|> Nothing == Nothing
 ```
 
-    instance extendMaybe :: Extend Maybe
+    instance altMaybe :: Alt Maybe
 
-#### `functorMaybe`
+#### `plusMaybe`
 
-The `Functor` instance allows functions to transform the contents of a
-`Just` with the `<$>` operator:
+The `Plus` instance provides a default `Maybe` value:
 
 ``` purescript
-f <$> Just x == Just (f x)
+empty :: Maybe _ == Nothing
 ```
 
-`Nothing` values are left untouched:
+    instance plusMaybe :: Plus Maybe
+
+#### `alternativeMaybe`
+
+The `Alternative` instance guarantees that there are both `Applicative` and
+`Plus` instances for `Maybe`.
+
+    instance alternativeMaybe :: Alternative Maybe
+
+#### `bindMaybe`
+
+The `Bind` instance allows sequencing of `Maybe` values and functions that
+return a `Maybe` by using the `>>=` operator:
 
 ``` purescript
-f <$> Nothing == Nothing
+Just x >>= f = f x
+Nothing >>= f = Nothing
 ```
 
-    instance functorMaybe :: Functor Maybe
+    instance bindMaybe :: Bind Maybe
 
 #### `monadMaybe`
 
@@ -176,25 +198,18 @@ The `MonadPlus` instance guarantees that there are both `Monad` and
 
     instance monadPlusMaybe :: MonadPlus Maybe
 
-#### `ordMaybe`
-
-The `Ord` instance allows `Maybe` values to be compared with
-`compare`, `>`, `>=`, `<` and `<=` whenever there is an `Ord` instance for
-the type the `Maybe` contains.
-
-`Nothing` is considered to be less than any `Just` value.
-
-    instance ordMaybe :: (Ord a) => Ord (Maybe a)
-
-#### `plusMaybe`
+#### `extendMaybe`
 
-The `Plus` instance provides a default `Maybe` value:
+The `Extend` instance allows sequencing of `Maybe` values and functions
+that accept a `Maybe a` and return a non-`Maybe` result using the
+`<<=` operator.
 
 ``` purescript
-empty :: Maybe _ == Nothing
+f <<= Nothing = Nothing
+f <<= Just x = Just (f x)
 ```
 
-    instance plusMaybe :: Plus Maybe
+    instance extendMaybe :: Extend Maybe
 
 #### `semigroupMaybe`
 
@@ -220,52 +235,27 @@ contains.
 
     instance showMaybe :: (Show a) => Show (Maybe a)
 
+#### `eqMaybe`
 
-### Values
-
-#### `fromMaybe`
-
-Takes a default value, and a `Maybe` value. If the `Maybe` value is
-`Nothing` the default value is returned, otherwise the value inside the
-`Just` is returned.
-
-``` purescript
-fromMaybe default Nothing == default
-fromMaybe default (Just x) == x
-```
-
-    fromMaybe :: forall a. a -> Maybe a -> a
-
-#### `isJust`
-
-Returns `true` when the `Maybe` value was constructed with `Just`.
-
-    isJust :: forall a. Maybe a -> Boolean
-
-#### `isNothing`
-
-Returns `true` when the `Maybe` value is `Nothing`.
+The `Eq` instance allows `Maybe` values to be checked for equality with
+`==` and inequality with `/=` whenever there is an `Eq` instance for the
+type the `Maybe` contains.
 
-    isNothing :: forall a. Maybe a -> Boolean
+    instance eqMaybe :: (Eq a) => Eq (Maybe a)
 
-#### `maybe`
+#### `ordMaybe`
 
-Takes a default value, a function, and a `Maybe` value. If the `Maybe`
-value is `Nothing` the default value is returned, otherwise the function
-is applied to the value inside the `Just` and the result is returned.
+The `Ord` instance allows `Maybe` values to be compared with
+`compare`, `>`, `>=`, `<` and `<=` whenever there is an `Ord` instance for
+the type the `Maybe` contains.
 
-``` purescript
-maybe default f Nothing == default
-maybe default f (Just x) == f x
-```
+`Nothing` is considered to be less than any `Just` value.
 
-    maybe :: forall a b. b -> (a -> b) -> Maybe a -> b
+    instance ordMaybe :: (Ord a) => Ord (Maybe a)
 
 
 ## Module Data.Maybe.Unsafe
 
-### Values
-
 #### `fromJust`
 
 A partial function that extracts the value from the `Just` data