11 files changed, 397 insertions, 4 deletions

diff --git a/src/gleam/atom.gleam b/src/gleam/atom.gleam
index e73b989..ccc7eb7 100644
--- a/src/gleam/atom.gleam
+++ b/src/gleam/atom.gleam
@@ -1,17 +1,27 @@
+/// A datatype and related functions for working with Erlang atoms.
+
 pub external type Atom;
 
+/// Error returned when a given Atom does not currently exist
 pub type AtomNotLoaded {
   AtomNotLoaded
 }
 
+/// Will return a value of type `Atom` that represents a specific Erlang
+/// atom from whom the string is its text representation if it exists.
+///
 pub external fn from_string(String) -> Result(Atom, AtomNotLoaded) =
   "gleam_stdlib" "atom_from_string";
 
 /// This function can create a new atom if one does not already exist for
 /// the given string. Atoms are not garbage collected so this can result
 /// in a memory leak if called over time on new values
+///
 pub external fn create_from_string(String) -> Atom =
   "gleam_stdlib" "atom_create_from_string";
 
+/// Retuns a `String` corresponding to the text representation of the given
+/// `Atom`
+///
 pub external fn to_string(Atom) -> String =
   "gleam_stdlib" "atom_to_string";
diff --git a/src/gleam/bool.gleam b/src/gleam/bool.gleam
index 6c77e7a..76476c3 100644
--- a/src/gleam/bool.gleam
+++ b/src/gleam/bool.gleam
@@ -1,5 +1,14 @@
+/// A set of utility functions for working with `Bool` values.
+
 import gleam/order.{Order}
 
+/// Returns the opposite Bool value
+///
+/// ## Examples
+/// ```gleam
+/// negate(True) == False
+/// ```
+///
 pub fn negate(bool: Bool) -> Bool {
   case bool {
     True -> False
@@ -7,6 +16,14 @@ pub fn negate(bool: Bool) -> Bool {
   }
 }
 
+/// Compares two bools and returns the first values Order to the second.
+///
+/// ## Examples
+/// ```gleam
+/// import gleam/order
+/// compare(True, False) == order.Gt
+/// ```
+///
 pub fn compare(a: Bool, b: Bool) -> Order {
   case a, b {
     True, True -> order.Eq
@@ -16,6 +33,15 @@ pub fn compare(a: Bool, b: Bool) -> Order {
   }
 }
 
+/// Returns `True` if either Bool value is `True`.
+///
+/// ## Examples
+/// ```gleam
+/// max(True, False) == True
+/// max(False, True) === True
+/// max(False, False) === False
+/// ```
+///
 pub fn max(a: Bool, b: Bool) -> Bool {
   case a {
     True -> True
@@ -23,6 +49,15 @@ pub fn max(a: Bool, b: Bool) -> Bool {
   }
 }
 
+/// Returns `False` if either Bool value is `False`.
+///
+/// ## Examples
+/// ```gleam
+/// max(True, False) == False
+/// max(False, True) === False
+/// max(False, False) === False
+/// ```
+///
 pub fn min(a: Bool, b: Bool) -> Bool {
   case a {
     False -> False
@@ -30,6 +65,14 @@ pub fn min(a: Bool, b: Bool) -> Bool {
   }
 }
 
+/// Returns a numeric representation of the value:
+///
+/// ## Examples
+/// ```gleam
+/// to_int(True) == 1
+/// to_int(False) == 0
+/// ```
+///
 pub fn to_int(bool: Bool) -> Int {
   case bool {
     False -> 0
diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam
index 05e523f..b080068 100644
--- a/src/gleam/dynamic.gleam
+++ b/src/gleam/dynamic.gleam
@@ -1,10 +1,11 @@
+/// `Dynamic` data is data that we don"t know the type of yet.
+/// We likely get data like this from interop with Erlang, or from
+/// IO with the outside world.
+
 import gleam/list as list_mod
 import gleam/atom
 import gleam/result
 
-/// `Dynamic` data is data that we don"t know the type of yet.
-/// We likely get data like this from interop with Erlang, or from
-/// IO with the outside world.
 pub external type Dynamic;
 
 /// Convert any Gleam data into `Dynamic` data.
@@ -18,27 +19,79 @@ pub external fn from(a) -> Dynamic = "gleam_stdlib" "identity";
 ///
 pub external fn unsafe_coerce(a) -> b = "gleam_stdlib" "identity";
 
+/// Safely cast a Dynamic value into a String.
+///
+/// ## Examples
+/// ```gleam
+/// string(from("Hello")) == Ok("Hello")
+/// string(from(123)) == Error("Expected a String, got `123`")
+/// ```
 pub external fn string(from: Dynamic) -> Result(String, String)
   = "gleam_stdlib" "decode_string"
 
+/// Safely cast a Dynamic value into a String.
+///
+/// ## Examples
+/// ```gleam
+/// int(from(123)) == Ok(123)
+/// int(from("Hello")) == Error("Expected an Int, got `\"Hello World\"`")
+/// ```
 pub external fn int(from: Dynamic) -> Result(Int, String)
   = "gleam_stdlib" "decode_int"
 
+/// Safely cast a Dynamic value into a Float.
+///
+/// ## Examples
+/// ```gleam
+/// float(from(2.0)) == Ok(2.0)
+/// float(from(123)) == Error("Expected a Float, got `123`")
+/// ```
 pub external fn float(from: Dynamic) -> Result(Float, String)
   = "gleam_stdlib" "decode_float"
 
+/// Safely cast a Dynamic value into an Atom.
+///
+/// ## Examples
+/// ```gleam
+/// import gleam/atom.{create_from_string, to_string}
+/// to_string(atom(from(create_from_string("hello")))) == "hello"
+/// atom(from(123)) == Error("Expected an Atom, got `123`")
+/// ```
 pub external fn atom(from: Dynamic) -> Result(atom.Atom, String)
   = "gleam_stdlib" "decode_atom"
 
+/// Safely cast a Dynamic value into a Bool.
+///
+/// ## Examples
+/// ```gleam
+/// bool(from(True)) == Ok(True)
+/// bool(from(123)) == Error("Expected a Bool, got `123`")
+/// ```
 pub external fn bool(from: Dynamic) -> Result(Bool, String)
   = "gleam_stdlib" "decode_bool"
 
+/// Safely cast a Dynamic value into a String.
+///
+/// ## Examples
+/// ```gleam
+/// import gleam/result
+/// let f = fn() { 1 }
+/// result.map(thunk(from(f)), fn(v) { v == f}) == True
+/// thunk(from(123)) == Error("Expected a zero arity function, got `123`")
+/// ```
 pub external fn thunk(from: Dynamic) -> Result(fn() -> Dynamic, String)
   = "gleam_stdlib" "decode_thunk"
 
 external fn list_dynamic(from: Dynamic) -> Result(List(Dynamic), String)
   = "gleam_stdlib" "decode_list"
 
+/// Safely cast a Dynamic value into a List of some type.
+///
+/// ## Examples
+/// ```gleam
+/// list(from(["a", "b", "c"]), string) == Ok(["a", "b", "c"])
+/// list(from([1, 2, 3]), string) == Error("Expected a List, got `[1, 2, 3]`")
+/// ```
 pub fn list(
   from dynamic: Dynamic,
   containing decoder_type: fn(Dynamic) -> Result(inner, String),
@@ -48,8 +101,24 @@ pub fn list(
   |> result.then(_, list_mod.traverse(_, decoder_type))
 }
 
+/// Returns a field from a Dynamic value representing a map if it exists.
+/// This will not succeed on a record.
+///
+/// ## Examples
+/// ```gleam
+/// import gleam/map
+/// field(from(map.new("Hello", "World")), "Hello") == Ok(Dynamic)
+/// field(from(123)) == Error("Expected a map with key `\"Hello\"`, got `123`")
+/// ```
 pub external fn field(from: Dynamic, named: a) -> Result(Dynamic, String)
   = "gleam_stdlib" "decode_field"
 
+/// Returns an element of a Dynamic value representing a tuple if it exists.
+///
+/// ## Examples
+/// ```gleam
+/// element(from(tuple(1, 2)), 0) == Ok(Dynamic)
+/// element(from(tuple(1, 2)), 2) == Error("Element position is out-of-bounds")
+/// ```
 pub external fn element(from: Dynamic, position: Int) -> Result(Dynamic, String)
   = "gleam_stdlib" "decode_element"
diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index 1eda66b..4ee941d 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -1,16 +1,42 @@
+/// A set of utility functions for working with `Float` values.
+
 import gleam/iodata
 import gleam/order.{Order}
 import gleam/result.{Option}
 
+/// Attempts to parse the String as a Float if possible
+///
+/// ## Examples
+/// ```gleam
+/// parse("2.3") == Some(2.3)
+/// parse("ABC") == None
+/// ```
+///
 pub external fn parse(String) -> Option(Float)
   = "gleam_stdlib" "parse_float";
 
+/// Returns the string representation of the provided
+/// `Float` value
+///
+/// ## Examples
+/// ```gleam
+/// to_string(2.3) == "2.3"
+/// ```
+///
 pub fn to_string(f: Float) -> String {
   f
   |> iodata.from_float
   |> iodata.to_string
 }
 
+
+/// Compares two `Floats`, returning an `Order`
+///
+/// ## Examples
+/// ```gleam
+/// compare(2.0, 2.3) == Lt
+/// ```
+///
 pub fn compare(a: Float, b: Float) -> Order {
   case a == b {
     True -> order.Eq
@@ -22,6 +48,13 @@ pub fn compare(a: Float, b: Float) -> Order {
   }
 }
 
+/// Compares two `Floats`, returning the smaller of the two
+///
+/// ## Examples
+/// ```gleam
+/// min(2.0, 2.3) == 2.0
+/// ```
+///
 pub fn min(a: Float, b: Float) -> Float {
   case a <. b {
     True -> a
@@ -29,6 +62,13 @@ pub fn min(a: Float, b: Float) -> Float {
   }
 }
 
+/// Compares two `Floats`, returning the larger of the two
+///
+/// ## Examples
+/// ```gleam
+/// max(2.0, 2.3) == 2.3
+/// ```
+///
 pub fn max(a: Float, b: Float) -> Float {
   case a >. b {
     True -> a
@@ -36,10 +76,39 @@ pub fn max(a: Float, b: Float) -> Float {
   }
 }
 
+/// Rounds the value to the next highest whole number as a Float
+///
+/// ## Examples
+/// ```gleam
+/// ceiling(2.3) == 3.0
+/// ```
+///
 pub external fn ceiling(Float) -> Float = "math" "ceil";
 
+/// Rounds the value to the next lowest whole number as a Float
+///
+/// ## Examples
+/// ```gleam
+/// floor(2.3) == 2.0
+/// ```
+///
 pub external fn floor(Float) -> Float = "math" "floor";
 
+/// Rounds the value to the nearest whole number as an Int
+///
+/// ## Examples
+/// ```gleam
+/// round(2.3) == 2
+/// round(2.5) == 3
+/// ```
+///
 pub external fn round(Float) -> Int = "erlang" "round";
 
+/// Returns the value as an Int, truncating all decimal digits.
+///
+/// ## Examples
+/// ```gleam
+/// truncate(2.4343434847383438) = 2
+/// ```
+///
 pub external fn truncate(Float) -> Int = "erlang" "trunc";
diff --git a/src/gleam/function.gleam b/src/gleam/function.gleam
index 6421dd1..0839def 100644
--- a/src/gleam/function.gleam
+++ b/src/gleam/function.gleam
@@ -1,3 +1,5 @@
+/// A set of utility higher-order functions for working with functions.
+
 /// Takes two functions and chains them together to form one function that takes
 /// the input from the first and returns the output of the second.
 pub fn compose(fun1: fn(a) -> b, fun2: fn(b) -> c) -> fn(a) -> c {
diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index 9ff5328..bd264fd 100644
--- a/src/gleam/int.gleam
+++ b/src/gleam/int.gleam
@@ -1,12 +1,47 @@
+// A set of utility functions for working with `Int` values
+
 import gleam/order.{Order}
 import gleam/result.{Option}
 
+/// Attempts to parse the String as an Int if possible
+///
+/// ## Examples
+/// ```gleam
+/// parse("2") == Some(2)
+/// parse("ABC") == None
+/// ```
+///
 pub external fn parse(String) -> Option(Int) = "gleam_stdlib" "parse_int";
 
+/// Returns the string representation of the provided
+/// `Int` value
+///
+/// ## Examples
+/// ```gleam
+/// to_string(2) == "2"
+/// ```
+///
 pub external fn to_string(Int) -> String = "erlang" "integer_to_binary"
 
+/// Returns the string representation of the provided
+/// `Int` value in the base provided.
+///
+/// ## Examples
+/// ```gleam
+/// to_base_string(2, 2) == "10"
+/// to_base_string(48, 16) == "30"
+/// to_base_string(48, 36) == "1C"
+/// ```
+///
 pub external fn to_base_string(Int, Int) -> String = "erlang" "integer_to_binary"
 
+/// Compares two `Int`, returning an `Order`
+///
+/// ## Examples
+/// ```gleam
+/// compare(2, 3) == Lt
+/// ```
+///
 pub fn compare(a: Int, b: Int) -> Order {
   case a == b {
     True -> order.Eq
@@ -18,6 +53,13 @@ pub fn compare(a: Int, b: Int) -> Order {
   }
 }
 
+/// Compares two `Int`, returning the smaller of the two
+///
+/// ## Examples
+/// ```gleam
+/// min(2, 3) == 2
+/// ```
+///
 pub fn min(a: Int, b: Int) -> Int {
   case a < b {
     True -> a
@@ -25,6 +67,13 @@ pub fn min(a: Int, b: Int) -> Int {
   }
 }
 
+/// Compares two `Int`, returning the larger of the two
+///
+/// ## Examples
+/// ```gleam
+/// max(2, 3) == 3
+/// ```
+///
 pub fn max(a: Int, b: Int) -> Int {
   case a > b {
     True -> a
@@ -32,10 +81,26 @@ pub fn max(a: Int, b: Int) -> Int {
   }
 }
 
+/// Returns whether the value provided is even
+///
+/// ## Examples
+/// ```gleam
+/// is_even(2) == True
+/// is_even(3) == False
+/// ```
+///
 pub fn is_even(x: Int) -> Bool {
   x % 2 == 0
 }
 
+/// Returns whether the value provided is odd
+///
+/// ## Examples
+/// ```gleam
+/// is_odd(3) == True
+/// is_odd(2) == False
+/// ```
+///
 pub fn is_odd(x: Int) -> Bool {
   x % 2 != 0
 }
diff --git a/src/gleam/iodata.gleam b/src/gleam/iodata.gleam
index 821581e..f34b40f 100644
--- a/src/gleam/iodata.gleam
+++ b/src/gleam/iodata.gleam
@@ -1,39 +1,71 @@
+/// Represents Erlang's `iodata` type and the associated functions
+/// to work with it.
+
 pub external type Iodata;
 
+/// Prepends the string `prefix` to `to`
+///
 pub external fn prepend(to: Iodata, prefix: String) -> Iodata =
   "gleam_stdlib" "iodata_prepend";
 
+/// Appends the string `suffix` to `to`
+///
 pub external fn append(to: Iodata, suffix: String) -> Iodata =
   "gleam_stdlib" "iodata_append";
 
+/// Prepends the Iodata `prefix` to `to`
+///
 pub external fn prepend_iodata(to: Iodata, prefix: Iodata) -> Iodata =
   "gleam_stdlib" "iodata_prepend";
 
+/// Prepends the Iodata `prefix` to `to`
+///
 pub external fn append_iodata(to: Iodata, suffix: Iodata) -> Iodata =
   "gleam_stdlib" "iodata_append";
 
+/// Builds an Iodata value from the supplied list of strings
+///
 pub external fn from_strings(List(String)) -> Iodata =
   "gleam_stdlib" "identity";
 
+/// Builds a new Iodata out of a list of Iodata
+///
 pub external fn concat(List(Iodata)) -> Iodata =
   "gleam_stdlib" "identity";
 
+/// Turns a `String` into an `Iodata`
+///
 pub external fn new(String) -> Iodata =
   "gleam_stdlib" "identity";
 
+/// Turns an `Iodata` into a `String`
+///
 pub external fn to_string(Iodata) -> String =
   "erlang" "iolist_to_binary";
 
+/// Returns the size of the Iodata in bytes
+///
 pub external fn byte_size(Iodata) -> Int =
   "erlang" "iolist_size";
 
+/// Creates an `Iodata` value from a `Float` value.
+///
 pub external fn from_float(Float) -> Iodata =
   "io_lib_format" "fwrite_g";
 
+/// Converts Iodata to a new Iodata where valid UTF-8 string data is
+/// lowercased 
+///
 pub external fn lowercase(Iodata) -> Iodata = "string" "lowercase"
 
+/// Converts Iodata to a new Iodata where valid UTF-8 string data is
+/// uppercased 
+///
 pub external fn uppercase(Iodata) -> Iodata = "string" "uppercase"
 
+/// Converts Iodata to a new Iodata where valid UTF-8 string data is
+/// reversed
+///
 pub external fn reverse(Iodata) -> Iodata = "string" "reverse"
 
 type Direction {
@@ -43,6 +75,8 @@ type Direction {
 external fn erl_split(Iodata, String, Direction) -> List(Iodata) =
   "string" "split"
 
+/// Splits the supplied Iodata by the pattern `on`
+///
 pub fn split(iodata: Iodata, on pattern: String) -> List(Iodata) {
   erl_split(iodata, pattern, All)
 }
@@ -50,6 +84,8 @@ pub fn split(iodata: Iodata, on pattern: String) -> List(Iodata) {
 external fn erl_replace(Iodata, String, String, Direction) -> Iodata =
   "string" "replace"
 
+/// Replaces all instances of `all` with the string `with`
+///
 pub fn replace(
   in iodata: Iodata,
   each pattern: String,
@@ -58,6 +94,10 @@ pub fn replace(
   erl_replace(iodata, pattern, substitute, All)
 }
 
+/// Prepends the string `prefix` to `to`
+///
 pub external fn is_equal(Iodata, Iodata) -> Bool = "string" "equal"
 
+/// Prepends the string `prefix` to `to`
+///
 pub external fn is_empty(Iodata) -> Bool = "string" "is_empty"
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index 86e88ea..4b832bc 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -8,9 +8,11 @@ pub type LengthMismatch {
 }
 
 /// Using the Erlang C BIF implementation.
+///
 pub external fn length(List(a)) -> Int = "erlang" "length"
 
 /// Using the Erlang C BIF implementation.
+///
 pub external fn reverse(List(a)) -> List(a) = "lists" "reverse"
 
 pub fn is_empty(list: List(a)) -> Bool {
diff --git a/src/gleam/order.gleam b/src/gleam/order.gleam
index 1c5a417..4b12af7 100644
--- a/src/gleam/order.gleam
+++ b/src/gleam/order.gleam
@@ -1,9 +1,19 @@
+/// Represents the result of a single comparison to determine the precise
+/// ordering of two values.
+
 pub type Order {
   Lt
   Eq
   Gt
 }
 
+/// Switches the evaluated ordering from one direction to the other
+///
+/// ## Examples
+/// ```gleam
+/// reverse(Lt) == Gt
+/// ```
+///
 pub fn reverse(order: Order) -> Order {
   case order {
     Lt -> Gt
@@ -12,6 +22,13 @@ pub fn reverse(order: Order) -> Order {
   }
 }
 
+/// Produces a numeric representation of the order
+///
+/// ## Examples
+/// ```gleam
+/// to_int(Lt) == -1
+/// ```
+///
 pub fn to_int(order: Order) -> Int {
   case order {
     Lt -> -1
@@ -20,7 +37,14 @@ pub fn to_int(order: Order) -> Int {
   }
 }
 
-pub fn compare(a: Order, b: Order) -> Order {
+/// Compares two Order values to one another, producing a new Order
+///
+/// ## Examples
+/// ```gleam
+/// compare(Eq, to: Lt) == Gt
+/// ```
+///
+pub fn compare(a: Order, to b: Order) -> Order {
   case a, b {
     x, y if x == y -> Eq
     Lt, _ | Eq, Gt -> Lt
@@ -28,6 +52,13 @@ pub fn compare(a: Order, b: Order) -> Order {
   }
 }
 
+/// Returns the highest of two orders
+///
+/// ## Examples
+/// ```gleam
+/// max(Eq, Lt) == Eq
+/// ```
+///
 pub fn max(a: Order, b: Order) -> Order {
   case a, b {
     Gt, _ -> Gt
@@ -36,6 +67,13 @@ pub fn max(a: Order, b: Order) -> Order {
   }
 }
 
+/// Returns the lowest of two orders
+///
+/// ## Examples
+/// ```gleam
+/// min(Eq, Lt) == Lt
+/// ```
+///
 pub fn min(a: Order, b: Order) -> Order {
   case a, b {
     Lt, _ -> Lt
diff --git a/src/gleam/pair.gleam b/src/gleam/pair.gleam
index 4cbce53..64b4212 100644
--- a/src/gleam/pair.gleam
+++ b/src/gleam/pair.gleam
@@ -1,23 +1,62 @@
+// A set of utility functions for working with 2-tuples, or pairs.
+
+/// Returns the first element in a pair.
+///
+/// ## Examples
+/// ```gleam
+/// first(tuple(1, 2)) = 1
+/// ```
+///
 pub fn first(pair: tuple(a, b)) -> a {
   let tuple(a, _) = pair
   a
 }
 
+/// Returns the second element in a pair.
+///
+/// ## Examples
+/// ```gleam
+/// second(tuple(1, 2)) = 2
+/// ```
+///
 pub fn second(pair: tuple(a, b)) -> b {
   let tuple(_, a) = pair
   a
 }
 
+/// Returns a new pair with the elements swapped.
+///
+/// ## Examples
+/// ```gleam
+/// swap(tuple(1, 2)) = tuple(2, 1)
+/// ```
+///
 pub fn swap(pair: tuple(a, b)) -> tuple(b, a) {
   let tuple(a, b) = pair
   tuple(b, a)
 }
 
+/// Returns a new pair with the first element having had `with` applied to
+/// it.
+///
+/// ## Examples
+/// ```gleam
+/// map_first(tuple(1, 2), fn(n) { n * 2 }) = 2
+/// ```
+///
 pub fn map_first(of pair: tuple(a, b), with fun: fn(a) -> c) -> tuple(c, b) {
   let tuple(a, b) = pair
   tuple(fun(a), b)
 }
 
+/// Returns a new pair with the second element having had `with` applied to
+/// it.
+///
+/// ## Examples
+/// ```gleam
+/// map_second(tuple(1, 2), fn(n) { n * 2 }) = 4
+/// ```
+///
 pub fn map_second(of pair: tuple(a, b), with fun: fn(b) -> c) -> tuple(a, c) {
   let tuple(a, b) = pair
   tuple(a, fun(b))
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index 1aa7ff5..5b3170d 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -1,6 +1,8 @@
 /// Result represents the result of something that may succeed or fail.
 /// `Ok` means it was successful, `Error` means it failed.
 
+/// Returns whether the value is Ok
+///
 pub fn is_ok(result: Result(a, e)) -> Bool {
   case result {
     Error(_) -> False
@@ -8,6 +10,7 @@ pub fn is_ok(result: Result(a, e)) -> Bool {
   }
 }
 
+/// Returns whether the value is Error
 pub fn is_error(result: Result(a, e)) -> Bool {
   case result {
     Ok(_) -> False
@@ -15,6 +18,9 @@ pub fn is_error(result: Result(a, e)) -> Bool {
   }
 }
 
+/// Executes the function `with` on inner value when Result is Ok, will noop
+/// if it is Error
+///
 pub fn map(
   over result: Result(a, e),
   with fun: fn(a) -> b,
@@ -25,6 +31,9 @@ pub fn map(
   }
 }
 
+/// Will execute the function `with` on inner value  when Result is Err, will noop
+/// if it is Ok
+///
 pub fn map_error(
   over result: Result(a, e),
   with fun: fn(e) -> f,
@@ -35,6 +44,8 @@ pub fn map_error(
   }
 }
 
+/// Will unnest the inner value of a result nested within another result
+///
 pub fn flatten(result: Result(Result(a, e), e)) -> Result(a, e) {
   case result {
     Ok(x) -> x
@@ -42,6 +53,8 @@ pub fn flatten(result: Result(Result(a, e), e)) -> Result(a, e) {
   }
 }
 
+/// An alias of `map`
+///
 pub fn then(
   result: Result(a, e),
   apply fun: fn(a) -> Result(b, e),
@@ -52,6 +65,9 @@ pub fn then(
   }
 }
 
+/// Will return the inner value of a Ok value.  If an error, will
+/// return the value provided as `or`
+///
 pub fn unwrap(result: Result(a, e), or default: a) -> a {
   case result {
     Ok(v) -> v