Merge pull request #244 from maxsnew/dev

New style docs for Maybe and Either

libraries/Either.elm

@@ -1,51 +1,76 @@
-
 module Either where
 
+{-| Represents any data that can take two different types.
+
+# Type and Constructors
+@docs Either, Left, Right
+
+# Taking Eithers apart
+@docs either, isLeft, isRight
+
+# Eithers and Lists
+@docs lefts, rights, partition, consLeft, consRight, consEither
+
+-}
+
 import List
 
--- Represents any data that can take two different types.
---
--- This can also be used for error handling `(Either String a)` where error
--- messages are stored on the left, and the correct values (“right”
--- values) are stored on the right.
+{-| This can also be used for error handling `(Either String a)` where
+    error messages are stored on the left, and the correct values
+    (“right” values) are stored on the right.
+-}
 data Either a b = Left a | Right b
 
--- Apply the first function to a `Left` and the second function to a `Right`.
--- This allows the extraction of a value from an `Either`.
+{-| Apply the first function to a `Left` and the second function to a `Right`.
+    This allows the extraction of a value from an `Either`.
+-}
 either : (a -> c) -> (b -> c) -> Either a b -> c
 either f g e = case e of { Left x -> f x ; Right y -> g y }
 
--- True if the value is a `Left`.
+{-| True if the value is a `Left`. -}
 isLeft : Either a b -> Bool
 isLeft e = case e of { Left  _ -> True ; _ -> False }
 
--- True if the value is a `Right`.
+{-| True if the value is a `Right`. -}
 isRight : Either a b -> Bool
 isRight e = case e of { Right _ -> True ; _ -> False }
 
--- Keep only the values held in `Left` values.
+{-| Keep only the values held in `Left` values. -}
 lefts : [Either a b] -> [a]
 lefts es = List.foldr consLeft [] es
 
--- Keep only the values held in `Right` values.
+{-| Keep only the values held in `Right` values. -}
 rights : [Either a b] -> [b]
 rights es = List.foldr consRight [] es
 
--- Split into two lists, lefts on the left and rights on the right. So we
--- have the equivalence: `(partition es == (lefts es, rights es))`
+{-| Split into two lists, lefts on the left and rights on the right. So we
+    have the equivalence: `(partition es == (lefts es, rights es))`
+-}
 partition : [Either a b] -> ([a],[b])
 partition es = List.foldr consEither ([],[]) es
 
+{-| If `Left`, add the value to the front of the list. 
+    If `Right`, return the list unchanged
+-}
+consLeft : Either a b -> [a] -> [a]
 consLeft e vs =
     case e of
       Left  v -> v::vs
       Right _ -> vs
 
+{-| If `Right`, add the value to the front of the list.
+    If `Left`, return the list unchanged.
+-}
+consRight : Either a b -> [b] -> [b]
 consRight e vs =
     case e of
       Left  _ -> vs
       Right v -> v::vs
 
+{-| If `Left`, add the value to the left list.
+    If `Right`, add the value to the right list.
+-}
+consEither : Either a b -> ([a], [b]) -> ([a], [b])
 consEither e (ls,rs) =
     case e of
       Left  l -> (l::ls,rs)

libraries/Maybe.elm

@@ -1,34 +1,52 @@
-
 module Maybe where
 
+{-| Represents an optional value.
+
+# Type and Constructors
+@docs Maybe, Just, Nothing
+
+# Taking Maybes apart
+@docs maybe, isJust, isNothing
+
+# Maybes and Lists
+@docs cons, justs
+-}
+
 import Basics (not, (.))
 import List (foldr)
 
--- The Maybe datatype. Useful when a computation may or may not
--- result in a value (e.g. logarithm is defined only for positive numbers).
+{-| The Maybe datatype. Useful when a computation may or may not
+    result in a value (e.g. logarithm is defined only for positive
+    numbers). 
+-}
 data Maybe a = Just a | Nothing
 
--- Apply a function to the contents of a `Maybe`.
--- Return default when given `Nothing`.
+{-| Apply a function to the contents of a `Maybe`.
+    Return default when given `Nothing`.
+-}
 maybe : b -> (a -> b) -> Maybe a -> b
 maybe b f m = case m of
                 Just v  -> f v
                 Nothing -> b
 
--- Check if constructed with `Just`.
+{-| Check if constructed with `Just`. 
+-}
 isJust : Maybe a -> Bool
 isJust = maybe False (\_ -> True)
 
--- Check if constructed with `Nothing`.
+{-| Check if constructed with `Nothing`.
+-}
 isNothing : Maybe a -> Bool
 isNothing = not . isJust
 
 
--- If `Just`, adds the value to the front of the list.
--- If `Nothing`, list is unchanged.
+{-| If `Just`, adds the value to the front of the list.
+    If `Nothing`, list is unchanged.
+-}
 cons : Maybe a -> [a] -> [a]
 cons mx xs = maybe xs (\x -> x :: xs) mx
 
--- Filters out Nothings and extracts the remaining values.
+{-| Filters out Nothings and extracts the remaining values.
+-}
 justs : [Maybe a] -> [a]
 justs = foldr cons []