git.iko.soy/elk
on master help sign in
Merge pull request #244 from maxsnew/dev

New style docs for Maybe and Either

commitbcae123cfd1abfd01eca64a046d3afa9cfe8299d authorEvan Czaplicki <info@elm-lang.org> dateSun 8 Sep 2013, 15:19 (13 years ago) parentd6d0ba7ac635ca
2 files changed+67−24
compare with master
unifiedsplit
libraries/Either.elm+39−14 libraries/Maybe.elm+28−10
libraries/Either.elm+39−14
@@ -1,51 +1,76 @@
1−
21module Either where
32
3+{-| Represents any data that can take two different types.
4+
5+# Type and Constructors
6+@docs Either, Left, Right
7+
8+# Taking Eithers apart
9+@docs either, isLeft, isRight
10+
11+# Eithers and Lists
12+@docs lefts, rights, partition, consLeft, consRight, consEither
13+
14+-}
15+
416import List
517
6−-- Represents any data that can take two different types.
7−--
8−-- This can also be used for error handling `(Either String a)` where error
9−-- messages are stored on the left, and the correct values (&ldquo;right&rdquo;
10−-- values) are stored on the right.
18+{-| This can also be used for error handling `(Either String a)` where
19+ error messages are stored on the left, and the correct values
20+ (&ldquo;right&rdquo; values) are stored on the right.
21+-}
1122data Either a b = Left a | Right b
1223
13−-- Apply the first function to a `Left` and the second function to a `Right`.
14−-- This allows the extraction of a value from an `Either`.
24+{-| Apply the first function to a `Left` and the second function to a `Right`.
25+ This allows the extraction of a value from an `Either`.
26+-}
1527either : (a -> c) -> (b -> c) -> Either a b -> c
1628either f g e = case e of { Left x -> f x ; Right y -> g y }
1729
18−-- True if the value is a `Left`.
30+{-| True if the value is a `Left`. -}
1931isLeft : Either a b -> Bool
2032isLeft e = case e of { Left _ -> True ; _ -> False }
2133
22−-- True if the value is a `Right`.
34+{-| True if the value is a `Right`. -}
2335isRight : Either a b -> Bool
2436isRight e = case e of { Right _ -> True ; _ -> False }
2537
26−-- Keep only the values held in `Left` values.
38+{-| Keep only the values held in `Left` values. -}
2739lefts : [Either a b] -> [a]
2840lefts es = List.foldr consLeft [] es
2941
30−-- Keep only the values held in `Right` values.
42+{-| Keep only the values held in `Right` values. -}
3143rights : [Either a b] -> [b]
3244rights es = List.foldr consRight [] es
3345
34−-- Split into two lists, lefts on the left and rights on the right. So we
35−-- have the equivalence: `(partition es == (lefts es, rights es))`
46+{-| Split into two lists, lefts on the left and rights on the right. So we
47+ have the equivalence: `(partition es == (lefts es, rights es))`
48+-}
3649partition : [Either a b] -> ([a],[b])
3750partition es = List.foldr consEither ([],[]) es
3851
52+{-| If `Left`, add the value to the front of the list.
53+ If `Right`, return the list unchanged
54+-}
55+consLeft : Either a b -> [a] -> [a]
3956consLeft e vs =
4057 case e of
4158 Left v -> v::vs
4259 Right _ -> vs
4360
61+{-| If `Right`, add the value to the front of the list.
62+ If `Left`, return the list unchanged.
63+-}
64+consRight : Either a b -> [b] -> [b]
4465consRight e vs =
4566 case e of
4667 Left _ -> vs
4768 Right v -> v::vs
4869
70+{-| If `Left`, add the value to the left list.
71+ If `Right`, add the value to the right list.
72+-}
73+consEither : Either a b -> ([a], [b]) -> ([a], [b])
4974consEither e (ls,rs) =
5075 case e of
5176 Left l -> (l::ls,rs)
libraries/Maybe.elm+28−10
@@ -1,34 +1,52 @@
1−
21module Maybe where
32
3+{-| Represents an optional value.
4+
5+# Type and Constructors
6+@docs Maybe, Just, Nothing
7+
8+# Taking Maybes apart
9+@docs maybe, isJust, isNothing
10+
11+# Maybes and Lists
12+@docs cons, justs
13+-}
14+
415import Basics (not, (.))
516import List (foldr)
617
7−-- The Maybe datatype. Useful when a computation may or may not
8−-- result in a value (e.g. logarithm is defined only for positive numbers).
18+{-| The Maybe datatype. Useful when a computation may or may not
19+ result in a value (e.g. logarithm is defined only for positive
20+ numbers).
21+-}
922data Maybe a = Just a | Nothing
1023
11−-- Apply a function to the contents of a `Maybe`.
12−-- Return default when given `Nothing`.
24+{-| Apply a function to the contents of a `Maybe`.
25+ Return default when given `Nothing`.
26+-}
1327maybe : b -> (a -> b) -> Maybe a -> b
1428maybe b f m = case m of
1529 Just v -> f v
1630 Nothing -> b
1731
18−-- Check if constructed with `Just`.
32+{-| Check if constructed with `Just`.
33+-}
1934isJust : Maybe a -> Bool
2035isJust = maybe False (\_ -> True)
2136
22−-- Check if constructed with `Nothing`.
37+{-| Check if constructed with `Nothing`.
38+-}
2339isNothing : Maybe a -> Bool
2440isNothing = not . isJust
2541
2642
27−-- If `Just`, adds the value to the front of the list.
28−-- If `Nothing`, list is unchanged.
43+{-| If `Just`, adds the value to the front of the list.
44+ If `Nothing`, list is unchanged.
45+-}
2946cons : Maybe a -> [a] -> [a]
3047cons mx xs = maybe xs (\x -> x :: xs) mx
3148
32−-- Filters out Nothings and extracts the remaining values.
49+{-| Filters out Nothings and extracts the remaining values.
50+-}
3351justs : [Maybe a] -> [a]
3452justs = foldr cons []