Alter example doc syntax, more list docs

12 files changed, 735 insertions, 310 deletions

diff --git a/src/gleam/atom.gleam b/src/gleam/atom.gleam
index c8fc79c..a806fc8 100644
--- a/src/gleam/atom.gleam
+++ b/src/gleam/atom.gleam
@@ -28,10 +28,12 @@ pub type FromStringError {
 ///
 /// ## Examples
 ///
-/// ```
-/// from_string("ok") == Ok(create_from_string("ok"))
-/// from_string("some_new_atom") == Error(AtomNotLoaded)
-/// ```
+///    > from_string("ok")
+///    Ok(create_from_string("ok"))
+///
+///    > from_string("some_new_atom")
+///    Error(AtomNotLoaded)
+///
 ///
 pub external fn from_string(String) -> Result(Atom, FromStringError) =
   "gleam_stdlib" "atom_from_string";
@@ -53,10 +55,9 @@ pub external fn create_from_string(String) -> Atom =
 ///
 /// ## Examples
 ///
-/// ```
-/// let ok_atom = create_from_string("ok")
-/// to_string(ok_atom) == "ok"
-/// ```
+///    > let ok_atom = create_from_string("ok")
+///    > to_string(ok_atom)
+///    "ok"
 ///
 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 a1c7ede..8a01235 100644
--- a/src/gleam/bool.gleam
+++ b/src/gleam/bool.gleam
@@ -14,9 +14,9 @@ pub type Bool =
 /// Returns the opposite Bool value
 ///
 /// ## Examples
-/// ```gleam
-/// negate(True) == False
-/// ```
+///    > negate(True)
+///    False
+///
 ///
 pub fn negate(bool: Bool) -> Bool {
   case bool {
@@ -28,10 +28,10 @@ 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
-/// ```
+///    > compare(True, False)
+///    order.Gt
+///
 ///
 pub fn compare(a: Bool, b: Bool) -> Order {
   case a, b {
@@ -45,11 +45,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
-/// ```
+///    > max(True, False)
+///    True
+///
+///    > max(False, True)
+///    True
+///
+///    > max(False, False)
+///    False
+///
 ///
 pub fn max(a: Bool, b: Bool) -> Bool {
   case a {
@@ -61,11 +65,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
-/// ```
+///    > max(True, False)
+///    False
+///
+///    > max(False, True)
+///    False
+///
+///    > max(False, False)
+///    False
+///
 ///
 pub fn min(a: Bool, b: Bool) -> Bool {
   case a {
@@ -77,10 +85,12 @@ 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
-/// ```
+///    > to_int(True)
+///    1
+///
+///    > to_int(False)
+///    0
+///
 ///
 pub fn to_int(bool: Bool) -> Int {
   case bool {
diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam
index 0e54ae1..488ad45 100644
--- a/src/gleam/dynamic.gleam
+++ b/src/gleam/dynamic.gleam
@@ -21,63 +21,75 @@ 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`")
-/// ```
+///    > 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\"`")
-/// ```
+///    > 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`")
-/// ```
+///    > 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
-/// atom(from(atom.create_from_string("hello"))) == OK("hello")
-/// atom(from(123)) == Error("Expected an Atom, got `123`")
-/// ```
+///    > atom(from(atom.create_from_string("hello")))
+///    OK("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`")
-/// ```
+///    > 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 }
-/// thunk(from(f)) |> result.is_ok == True
-/// thunk(from(123)) == Error("Expected a zero arity function, got `123`")
-/// ```
+///    > thunk(from(f)) |> result.is_ok
+///    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"
 
@@ -87,10 +99,12 @@ external fn list_dynamic(from: Dynamic) -> Result(List(Dynamic), String)
 /// 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]`")
-/// ```
+///    > 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),
@@ -104,20 +118,24 @@ pub fn list(
 /// 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`")
-/// ```
+///    > 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")
-/// ```
+///    > 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 b02cd94..499c7fc 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -8,10 +8,12 @@ pub type Float =
 /// Attempts to parse the String as a Float if possible
 ///
 /// ## Examples
-/// ```gleam
-/// parse("2.3") == Some(2.3)
-/// parse("ABC") == None
-/// ```
+///    > parse("2.3")
+///    Some(2.3)
+///
+///    > parse("ABC")
+///    None
+///
 ///
 pub external fn parse(String) -> Option(Float)
   = "gleam_stdlib" "parse_float";
@@ -20,9 +22,9 @@ pub external fn parse(String) -> Option(Float)
 /// `Float` value
 ///
 /// ## Examples
-/// ```gleam
-/// to_string(2.3) == "2.3"
-/// ```
+///    > to_string(2.3)
+///    "2.3"
+///
 ///
 pub fn to_string(f: Float) -> String {
   f
@@ -34,9 +36,9 @@ pub fn to_string(f: Float) -> String {
 /// Compares two `Floats`, returning an `Order`
 ///
 /// ## Examples
-/// ```gleam
-/// compare(2.0, 2.3) == Lt
-/// ```
+///    > compare(2.0, 2.3)
+///    Lt
+///
 ///
 pub fn compare(a: Float, b: Float) -> Order {
   case a == b {
@@ -52,9 +54,9 @@ 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
-/// ```
+///    > min(2.0, 2.3)
+///    2.0
+///
 ///
 pub fn min(a: Float, b: Float) -> Float {
   case a <. b {
@@ -66,9 +68,9 @@ 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
-/// ```
+///    > max(2.0, 2.3)
+///    2.3
+///
 ///
 pub fn max(a: Float, b: Float) -> Float {
   case a >. b {
@@ -80,36 +82,38 @@ 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
-/// ```
+///    > 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
-/// ```
+///    > 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
-/// ```
+///    > 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
-/// ```
+///    > truncate(2.4343434847383438)
+///    2
+///
 ///
 pub external fn truncate(Float) -> Int = "erlang" "trunc";
diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index a2fd502..95992fd 100644
--- a/src/gleam/int.gleam
+++ b/src/gleam/int.gleam
@@ -7,10 +7,12 @@ pub type Int =
 /// Attempts to parse the String as an Int if possible
 ///
 /// ## Examples
-/// ```gleam
-/// parse("2") == Some(2)
-/// parse("ABC") == None
-/// ```
+///    > parse("2")
+///    Some(2)
+///
+///    > parse("ABC")
+///    None
+///
 ///
 pub external fn parse(String) -> Option(Int) = "gleam_stdlib" "parse_int";
 
@@ -18,9 +20,9 @@ pub external fn parse(String) -> Option(Int) = "gleam_stdlib" "parse_int";
 /// `Int` value
 ///
 /// ## Examples
-/// ```gleam
-/// to_string(2) == "2"
-/// ```
+///    > to_string(2)
+///    "2"
+///
 ///
 pub external fn to_string(Int) -> String = "erlang" "integer_to_binary"
 
@@ -28,20 +30,24 @@ pub external fn to_string(Int) -> String = "erlang" "integer_to_binary"
 /// `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"
-/// ```
+///    > 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
-/// ```
+///    > compare(2, 3)
+///    Lt
+///
 ///
 pub fn compare(a: Int, b: Int) -> Order {
   case a == b {
@@ -57,9 +63,9 @@ pub fn compare(a: Int, b: Int) -> Order {
 /// Compares two `Int`, returning the smaller of the two
 ///
 /// ## Examples
-/// ```gleam
-/// min(2, 3) == 2
-/// ```
+///    > min(2, 3)
+///    2
+///
 ///
 pub fn min(a: Int, b: Int) -> Int {
   case a < b {
@@ -71,9 +77,9 @@ pub fn min(a: Int, b: Int) -> Int {
 /// Compares two `Int`, returning the larger of the two
 ///
 /// ## Examples
-/// ```gleam
-/// max(2, 3) == 3
-/// ```
+///    > max(2, 3)
+///    3
+///
 ///
 pub fn max(a: Int, b: Int) -> Int {
   case a > b {
@@ -85,10 +91,12 @@ 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
-/// ```
+///    > is_even(2)
+///    True
+///
+///    > is_even(3)
+///    False
+///
 ///
 pub fn is_even(x: Int) -> Bool {
   x % 2 == 0
@@ -97,10 +105,12 @@ pub fn is_even(x: Int) -> Bool {
 /// Returns whether the value provided is odd
 ///
 /// ## Examples
-/// ```gleam
-/// is_odd(3) == True
-/// is_odd(2) == False
-/// ```
+///    > 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 a919cf1..5310b5e 100644
--- a/src/gleam/iodata.gleam
+++ b/src/gleam/iodata.gleam
@@ -128,10 +128,12 @@ pub fn replace(
 ///
 /// ## Examples
 ///
-/// ```
-/// from_strings(["a", "b"]) == new("ab") == False
-/// is_equal(from_strings(["a", "b"]), new("ab")) == True
-/// ```
+///    > from_strings(["a", "b"]) == new("ab")
+///    False
+///
+///    > is_equal(from_strings(["a", "b"]), new("ab"))
+///    True
+///
 ///
 pub external fn is_equal(Iodata, Iodata) -> Bool = "string" "equal"
 
@@ -139,10 +141,14 @@ pub external fn is_equal(Iodata, Iodata) -> Bool = "string" "equal"
 ///
 /// ## Examples
 ///
-/// ```
-/// new("ok") |> is_empty == False
-/// new("") |> is_empty == True
-/// from_strings([]) |> is_empty == True
-/// ```
+///    > new("ok") |> is_empty
+///    False
+///
+///    > new("") |> is_empty
+///    True
+///
+///    > from_strings([]) |> is_empty
+///    True
+///
 ///
 pub external fn is_empty(Iodata) -> Bool = "string" "is_empty"
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index 89d5ca4..a721294 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -8,18 +8,15 @@
 ////
 //// There is a dedicated syntax for prefixing to a list:
 ////
-//// ```
-//// let new_list = [1, 2, ..existing_list]
-//// ```
+////    let new_list = [1, 2, ..existing_list]
 ////
 //// And a matching syntax for getting the first elements of a list:
 ////
-//// ```
-//// case list {
-////   [first_element, ..rest] -> first_element
-////   _ -> "this pattern matches when the list is empty"
-//// }
-//// ```
+////    case list {
+////      [first_element, ..rest] -> first_element
+////      _ -> "this pattern matches when the list is empty"
+////    }
+////
 
 import gleam/int
 import gleam/pair
@@ -45,11 +42,15 @@ pub type LengthMismatch {
 ///
 /// ## Examples
 ///
-/// ```
-/// length([]) == 0
-/// length([1]) == 1
-/// length([1, 2]) == 2
-/// ```
+///    > length([])
+///    0
+///
+///    > length([1])
+///    1
+///
+///    > length([1, 2])
+///    2
+///
 ///
 pub external fn length(of: List(a)) -> Int = "erlang" "length"
 
@@ -64,11 +65,15 @@ pub external fn length(of: List(a)) -> Int = "erlang" "length"
 ///
 /// ## Examples
 ///
-/// ```
-/// reverse([]) == []
-/// reverse([1]) == [1]
-/// reverse([1, 2]) == [2, 1]
-/// ```
+///    > reverse([])
+///    []
+///
+///    > reverse([1])
+///    [1]
+///
+///    > reverse([1, 2])
+///    [2, 1]
+///
 ///
 pub external fn reverse(List(a)) -> List(a) = "lists" "reverse"
 
@@ -78,11 +83,15 @@ pub external fn reverse(List(a)) -> List(a) = "lists" "reverse"
 ///
 /// ## Examples
 ///
-/// ```
-/// is_empty([]) == True
-/// is_empty([1]) == False
-/// is_empty([1, 1]) == False
-/// ```
+///    > is_empty([])
+///    True
+///
+///    > is_empty([1])
+///    False
+///
+///    > is_empty([1, 1])
+///    False
+///
 ///
 pub fn is_empty(list: List(a)) -> Bool {
   list == []
@@ -95,13 +104,21 @@ pub fn is_empty(list: List(a)) -> Bool {
 ///
 /// ## Examples
 ///
-/// ```
-/// contains([], 0) == True
-/// contains([0], 0) == True
-/// contains([1], 0) == False
-/// contains([1, 1], 0) == False
-/// contains([1, 0], 0) == True
-/// ```
+///    > contains([], 0)
+///    True
+///
+///    > contains([0], 0)
+///    True
+///
+///    > contains([1], 0)
+///    False
+///
+///    > contains([1, 1], 0)
+///    False
+///
+///    > contains([1, 0], 0)
+///    True
+///
 ///
 pub fn contains(list: List(a), has elem: a) -> Bool {
   case list {
@@ -114,11 +131,15 @@ pub fn contains(list: List(a), has elem: a) -> Bool {
 ///
 /// ## Examples
 ///
-/// ```
-/// head([]) == Error(Nil)
-/// head([0]) == Ok(0)
-/// head([1, 2]) == Ok(1)
-/// ```
+///    > head([])
+///    Error(Nil)
+///
+///    > head([0])
+///    Ok(0)
+///
+///    > head([1, 2])
+///    Ok(1)
+///
 ///
 pub fn head(list: List(a)) -> Option(a) {
   case list {
@@ -134,11 +155,15 @@ pub fn head(list: List(a)) -> Option(a) {
 ///
 /// ## Examples
 ///
-/// ```
-/// tail([]) == Error(Nil)
-/// tail([0]) == Ok([])
-/// tail([1, 2]) == Ok([2])
-/// ```
+///    > tail([])
+///    Error(Nil)
+///
+///    > tail([0])
+///    Ok([])
+///
+///    > tail([1, 2])
+///    Ok([2])
+///
 ///
 pub fn tail(list: List(a)) -> Option(List(a)) {
   case list {
@@ -160,6 +185,18 @@ fn do_filter(list: List(a), fun: fn(a) -> Bool, acc: List(a)) -> List(a) {
   }
 }
 
+/// Returns a new list containing only the elements from the first list for
+/// which the given functions returns `True`.
+///
+/// ## Examples
+///
+///    > filter([2, 4, 6, 1], fn(x) { x > 2 })
+///    [4, 6]
+///
+///    > filter([2, 4, 6, 1], fn(x) { x > 6 })
+///    []
+///
+///
 pub fn filter(list: List(a), for predicate: fn(a) -> Bool) -> List(a) {
   do_filter(list, predicate, [])
 }
@@ -171,6 +208,15 @@ fn do_map(list: List(a), fun: fn(a) -> b, acc: List(b)) -> List(b) {
   }
 }
 
+/// Returns a new list containing only the elements of the first list after the
+/// function has been applied to each one.
+///
+/// ## Examples
+///
+///    > map([2, 4, 6], fn(x) { x * 2 })
+///    [4, 8, 12]
+///
+///
 pub fn map(list: List(a), with fun: fn(a) -> b) -> List(b) {
   do_map(list, fun, [])
 }
@@ -187,10 +233,23 @@ fn do_index_map(
   }
 }
 
+/// Returns a new list containing only the elements of the first list after the
+/// function has been applied to each one and their index.
+///
+/// The index starts at 0, so the first element is 0, the second is 1, and so
+/// on.
+///
+/// ## Examples
+///
+///    > index_map(["a", "b"], fn(i, x) { tuple(i, x) })
+///    [tuple(0, "a"), tuple(1, "b")]
+///
+///
 pub fn index_map(list: List(a), with fun: fn(Int, a) -> b) -> List(b) {
   do_index_map(list, fun, 0, [])
 }
 
+
 fn do_traverse(
   list: List(a),
   fun: fn(a) -> Result(b, e),
@@ -206,6 +265,31 @@ fn do_traverse(
   }
 }
 
+/// Takes a function that returns a Result applies it to each element in a
+/// given list in tern.
+///
+/// If the function returns `Ok(new_value)` for all elements in the list then a
+/// list of the new values is returned.
+///
+/// If the function returns `Error(reason)` for any of the elements then it is
+/// returned immediately. None of the elements in the list are processed after
+/// one returns an `Error`.
+///
+/// ## Examples
+///
+///    > traverse([1, 2, 3], fn(x) { Ok(x + 2) })
+///    Ok([3, 4, 5])
+///
+///    > traverse([1, 2, 3], fn(x) { Error(0) })
+///    Error(0)
+///
+///    > traverse([[1], [2, 3]], head)
+///    Ok([1, 2])
+///
+///    > traverse([[1], [], [2]], head)
+///    Error(Nil)
+///
+///
 pub fn traverse(
   list: List(a),
   with fun: fn(a) -> Result(b, e),
@@ -213,6 +297,23 @@ pub fn traverse(
   do_traverse(list, fun, [])
 }
 
+/// Returns a list that is the given list with up to the given number of
+/// elements removed from the front of the list.
+///
+/// If the element has less than the number of elements an empty list is
+/// returned.
+///
+/// This function runs in linear time but does not copy the list.
+///
+/// ## Examples
+///
+///    > drop([1, 2, 3, 4], 2)
+///    [3, 4]
+///
+///    > drop([1, 2, 3, 4], 9)
+///    []
+///
+///
 pub fn drop(from list: List(a), up_to n: Int) -> List(a) {
   case n <= 0 {
     True -> list
@@ -235,14 +336,50 @@ fn do_take(list: List(a), n: Int, acc: List(a)) -> List(a) {
   }
 }
 
+/// Returns a list containing the first given number of elements from the given
+/// list.
+///
+/// If the element has less than the number of elements then the full list is
+/// returned.
+///
+/// This function runs in linear time but does not copy the list.
+///
+/// ## Examples
+///
+///    > take([1, 2, 3, 4], 2)
+///    [1, 2]
+///
+///    > take([1, 2, 3, 4], 9)
+///    [1, 2, 3, 4]
+///
+///
 pub fn take(from list: List(a), up_to n: Int) -> List(a) {
   do_take(list, n, [])
 }
 
+/// Returns a new empty list.
+///
+/// ## Examples
+///
+///    > new()
+///    []
+///
+///
 pub fn new() -> List(a) {
   []
 }
 
+/// Join one list onto the end of another.
+///
+/// This function runs in linear time, and it traverses and copies the first
+/// list.
+///
+/// ## Examples
+///
+///    > append([1, 2], [3])
+///    [1, 2, 3]
+///
+///
 pub external fn append(List(a), List(a)) -> List(a)
   = "lists" "append";
 
@@ -253,10 +390,28 @@ fn do_flatten(lists: List(List(a)), acc: List(a)) -> List(a) {
   }
 }
 
+/// Flattens a list of lists into a single list.
+///
+/// This function runs in linear time, and it traverses and copies all the
+/// inner lists.
+///
+/// ## Examples
+///
+///    > flatten([[1], [2, 3], []])
+///    [1, 2, 3]
+///
+///
 pub fn flatten(lists: List(List(a))) -> List(a) {
   do_flatten(lists, [])
 }
 
+/// Reduce a list of elements into a single value by calling a given function
+/// on each element, going from left to right.
+///
+/// `fold([1, 2, 3], 0, add)` is the equivalent of `add(3, add(2, add(1, 0)))`.
+///
+/// This function runs in linear time.
+///
 pub fn fold(list: List(a), from initial: b, with fun: fn(a, b) -> b) -> b {
   case list {
     [] -> initial
@@ -264,6 +419,17 @@ pub fn fold(list: List(a), from initial: b, with fun: fn(a, b) -> b) -> b {
   }
 }
 
+/// Reduce a list of elements into a single value by calling a given function
+/// on each element, going from right to left.
+///
+/// `fold_right([1, 2, 3], 0, add)` is the equivalent of
+/// `add(1, add(2, add(3, 0)))`.
+///
+/// This function runs in linear time.
+///
+/// Unlike `fold` this function is not tail recursive. Where possible use
+/// `fold` instead as it will use less memory.
+///
 pub fn fold_right(
   list: List(a),
   from initial: b,
@@ -275,6 +441,24 @@ pub fn fold_right(
   }
 }
 
+/// Find the first element in a given list for which the given function returns
+/// True.
+///
+/// Returns `Error(Nil)` if no the function does not return True for any of the
+/// elements.
+///
+/// ## Examples
+///
+///    > find([1, 2, 3], fn(x) { x > 2 })
+///    Ok(3)
+///
+///    > find([1, 2, 3], fn(x) { x > 4 })
+///    Error(Nil)
+///
+///    > find([], fn(x) { True })
+///    Error(Nil)
+///
+///
 pub fn find(
   in haystack: List(a),
   one_that is_desired: fn(a) -> Bool,
@@ -289,6 +473,24 @@ pub fn find(
   }
 }
 
+/// Find the first element in a given list for which the given function returns
+/// `Ok(new_value)` and return the new value for that element.
+///
+/// Returns `Error(Nil)` if no the function does not return Ok for any of the
+/// elements.
+///
+/// ## Examples
+///
+///    > find_map([[], [2], [3]], head)
+///    Ok(2)
+///
+///    > find_map([[], []], head)
+///    Error(Nil)
+///
+///    > find_map([], head)
+///    Error(Nil)
+///
+///
 pub fn find_map(
   in haystack: List(a),
   with fun: fn(a) -> Option(b),
@@ -303,6 +505,22 @@ pub fn find_map(
   }
 }
 
+/// Returns True if the given function returns True for all the elements in
+/// the given list. If the function returns False for any of the elements it
+/// immediately returns False without checking the rest of the list.
+///
+/// ## Examples
+///
+///    > all([], fn(x) { x > 3 })
+///    True
+///
+///    > all([4, 5], fn(x) { x > 3 })
+///    True
+///
+///    > all([4, 3], fn(x) { x > 3 })
+///    False
+///
+///
 pub fn all(in list: List(a), satisfying predicate: fn(a) -> Bool) -> Bool {
   case list {
     [] -> True
@@ -314,6 +532,25 @@ pub fn all(in list: List(a), satisfying predicate: fn(a) -> Bool) -> Bool {
   }
 }
 
+/// Returns True if the given function returns True for any the elements in
+/// the given list. If the function returns True for any of the elements it
+/// immediately returns True without checking the rest of the list.
+///
+/// ## Examples
+///
+///    > any([], fn(x) { x > 3 })
+///    False
+///
+///    > any([4, 5], fn(x) { x > 3 })
+///    False
+///
+///    > any([4, 3], fn(x) { x > 3 })
+///    True
+///
+///    > any([3, 4], fn(x) { x > 3 })
+///    True
+///
+///
 pub fn any(in list: List(a), satisfying predicate: fn(a) -> Bool) -> Bool {
   case list {
     [] -> False
@@ -325,6 +562,26 @@ pub fn any(in list: List(a), satisfying predicate: fn(a) -> Bool) -> Bool {
   }
 }
 
+/// Takes two lists and returns a single list of 2 item tuples.
+///
+/// If one of the lists is longer than the other the remaining elements from
+/// the longer list are not used.
+///
+/// ## Examples
+///
+///    > zip([], [])
+///    []
+///
+///    > zip([1, 2], [3])
+///    [tuple(1, 3)]
+///
+///    > zip([1], [3, 4])
+///    [tuple(1, 3)]
+///
+///    > zip([1, 2], [3, 4])
+///    [tuple(1, 3), tuple(2, 4)]
+///
+///
 pub fn zip(xs: List(a), ys: List(b)) -> List(tuple(a, b)) {
   case xs, ys {
     [], _ -> []
@@ -333,6 +590,25 @@ pub fn zip(xs: List(a), ys: List(b)) -> List(tuple(a, b)) {
   }
 }
 
+/// Takes two lists and returns a single list of 2 item tuples.
+///
+/// If one of the lists is longer than the other an Error is returned.
+///
+/// ## Examples
+///
+///    > strict_zip([], [])
+///    Ok([])
+///
+///    > strict_zip([1, 2], [3])
+///    Error(LengthMismatch)
+///
+///    > strict_zip([1], [3, 4])
+///    Error(LengthMismatch)
+///
+///    > strict_zip([1, 2], [3, 4])
+///    Ok([tuple(1, 3), tuple(2, 4)])
+///
+///
 pub fn strict_zip(l1: List(a), l2: List(b)) -> Result(List(tuple(a, b)), LengthMismatch) {
   case length(of: l1) == length(of: l2) {
     True -> Ok(zip(l1, l2))
@@ -340,6 +616,19 @@ pub fn strict_zip(l1: List(a), l2: List(b)) -> Result(List(tuple(a, b)), LengthM
   }
 }
 
+/// Insert a given value between each existing element in a given list.
+///
+/// This function runs in linear time and copies the list.
+///
+/// ## Examples
+///
+///    > intersperse([1, 1, 1], 2)
+///    [1, 2, 1, 2, 1]
+///
+///    > intersperse([], 2)
+///    []
+///
+///
 pub fn intersperse(list: List(a), with elem: a) -> List(a) {
   case list {
     [] | [_] -> list
@@ -347,6 +636,20 @@ pub fn intersperse(list: List(a), with elem: a) -> List(a) {
   }
 }
 
+/// Return the element in the Nth position in the list, with 0 being the first
+/// position.
+///
+/// Error(Nil) is returned if the list is not long enough for the given index.
+///
+/// ## Examples
+///
+///    > at([1, 2, 3], 1)
+///    Ok(2)
+///
+///    > at([1, 2, 3], 5)
+///    Error(Nil)
+///
+///
 pub fn at(in list: List(a), get index: Int) -> Option(a) {
   case index < 0 {
     True -> result.none()
@@ -362,6 +665,16 @@ pub fn at(in list: List(a), get index: Int) -> Option(a) {
   }
 }
 
+/// Remove any duplicate elements from a given list.
+///
+/// This function returns in log-linear time (n log n).
+///
+/// ## Examples
+///
+///    > unique([1, 1, 1, 4, 7, 3, 3, 4])
+///    [1, 4, 7, 3]
+///
+///
 pub fn unique(list: List(a)) -> List(a) {
   case list {
     [] -> []
@@ -397,10 +710,27 @@ fn do_sort(list: List(a), compare: fn(a, a) -> Order, list_length: Int) -> List(
   }
 }
 
+/// Sort from smallest to largest based upon the ordering specified by a given
+/// function.
+///
 pub fn sort(list: List(a), sort_by compare: fn(a, a) -> Order) -> List(a) {
   do_sort(list, compare, length(list))
 }
 
+/// Create a list of ints ranging from a given start and finish.
+///
+/// ## Examples
+///
+///    > range(0, 0)
+///    []
+///
+///    > range(0, 5)
+///    [0, 1, 2, 3, 4]
+///
+///    > range(1, -5)
+///    [1, 0, -1, -2, -3, -4]
+///
+///
 pub fn range(from start: Int, to stop: Int) -> List(Int) {
   case int.compare(start, stop) {
     order.Eq -> []
@@ -416,6 +746,16 @@ fn do_repeat(a: a, times: Int, acc: List(a)) -> List(a) {
   }
 }
 
+/// Build a list of a given value a given number of times.
+///
+/// ## Examples
+///
+///    > repeat("a", times: 0)
+///    []
+///
+///    > repeat("a", times: 5)
+///    ["a", "a", "a", "a", "a"]
+///
 pub fn repeat(item a: a, times times: Int) -> List(a) {
   do_repeat(a, times, [])
 }
diff --git a/src/gleam/map.gleam b/src/gleam/map.gleam
index b5fd456..fd49433 100644
--- a/src/gleam/map.gleam
+++ b/src/gleam/map.gleam
@@ -22,10 +22,12 @@ pub external type Map(key, value);
 ///
 /// ## Examples
 ///
-/// ```
-/// new() |> size() == 0
-/// new() |> insert("key", "value") |> size() == 1
-/// ```
+///    > new() |> size()
+///    0
+///
+///    > new() |> insert("key", "value") |> size()
+///    1
+///
 ///
 pub external fn size(Map(k, v)) -> Int
   = "maps" "size"
@@ -37,10 +39,12 @@ pub external fn size(Map(k, v)) -> Int
 ///
 /// ## Examples
 ///
-/// ```
-/// new() |> to_list() == []
-/// new() |> insert("key", 0) |> to_list() == [tuple("key", 0)]
-/// ```
+///    > new() |> to_list()
+///    []
+///
+///    > new() |> insert("key", 0) |> to_list()
+///    [tuple("key", 0)]
+///
 ///
 pub external fn to_list(Map(key, value)) -> List(tuple(key, value))
   = "maps" "to_list"
@@ -60,10 +64,12 @@ external fn is_key(key, Map(key, v)) -> Bool
 ///
 /// ## Examples
 ///
-/// ```
-/// new() |> insert("a", 0) |> has_key("a") == True
-/// new() |> insert("a", 0) |> has_key("b") == False
-/// ```
+///    > new() |> insert("a", 0) |> has_key("a")
+///    True
+///
+///    > new() |> insert("a", 0) |> has_key("b")
+///    False
+///
 ///
 pub fn has_key(map: Map(k, v), key: k) -> Bool {
   is_key(key, map)
@@ -82,10 +88,12 @@ pub external fn new() -> Map(key, value)
 ///
 /// ## Examples
 ///
-/// ```
-/// new() |> insert("a", 0) |> get("a") == Ok(0)
-/// new() |> insert("a", 0) |> get("b") == Error(Nil)
-/// ```
+///    > new() |> insert("a", 0) |> get("a")
+///    Ok(0)
+///
+///    > new() |> insert("a", 0) |> get("b")
+///    Error(Nil)
+///
 ///
 pub external fn get(from: Map(key, value), get: key) -> Option(value)
   = "gleam_stdlib" "map_get";
@@ -100,10 +108,12 @@ external fn erl_insert(key, value, Map(key, value)) -> Map(key, value)
 ///
 /// ## Examples
 ///
-/// ```
-/// new() |> insert("a", 0) |> to_list == [tuple("a", 0)]
-/// new() |> insert("a", 0) |> insert("a", 5) |> to_list == [tuple("a", 5)]
-/// ```
+///    > new() |> insert("a", 0) |> to_list
+///    [tuple("a", 0)]
+///
+///    > new() |> insert("a", 0) |> insert("a", 5) |> to_list
+///    [tuple("a", 5)]
+///
 ///
 pub fn insert(into map: Map(k, v), for key: k, insert value: v) -> Map(k, v) {
   erl_insert(key, value, map)
diff --git a/src/gleam/order.gleam b/src/gleam/order.gleam
index ce58db0..5c4df19 100644
--- a/src/gleam/order.gleam
+++ b/src/gleam/order.gleam
@@ -9,9 +9,9 @@ pub type Order {
 /// Switches the evaluated ordering from one direction to the other
 ///
 /// ## Examples
-/// ```gleam
-/// reverse(Lt) == Gt
-/// ```
+///    > reverse(Lt)
+///    Gt
+///
 ///
 pub fn reverse(order: Order) -> Order {
   case order {
@@ -24,9 +24,9 @@ pub fn reverse(order: Order) -> Order {
 /// Produces a numeric representation of the order
 ///
 /// ## Examples
-/// ```gleam
-/// to_int(Lt) == -1
-/// ```
+///    > to_int(Lt)
+///    -1
+///
 ///
 pub fn to_int(order: Order) -> Int {
   case order {
@@ -39,9 +39,9 @@ pub fn to_int(order: Order) -> Int {
 /// Compares two Order values to one another, producing a new Order
 ///
 /// ## Examples
-/// ```gleam
-/// compare(Eq, to: Lt) == Gt
-/// ```
+///    > compare(Eq, to: Lt)
+///    Gt
+///
 ///
 pub fn compare(a: Order, to b: Order) -> Order {
   case a, b {
@@ -54,9 +54,9 @@ pub fn compare(a: Order, to b: Order) -> Order {
 /// Returns the highest of two orders
 ///
 /// ## Examples
-/// ```gleam
-/// max(Eq, Lt) == Eq
-/// ```
+///    > max(Eq, Lt)
+///    Eq
+///
 ///
 pub fn max(a: Order, b: Order) -> Order {
   case a, b {
@@ -69,9 +69,9 @@ pub fn max(a: Order, b: Order) -> Order {
 /// Returns the lowest of two orders
 ///
 /// ## Examples
-/// ```gleam
-/// min(Eq, Lt) == Lt
-/// ```
+///    > min(Eq, Lt)
+///    Lt
+///
 ///
 pub fn min(a: Order, b: Order) -> Order {
   case a, b {
diff --git a/src/gleam/pair.gleam b/src/gleam/pair.gleam
index 54fea2f..4a2e592 100644
--- a/src/gleam/pair.gleam
+++ b/src/gleam/pair.gleam
@@ -1,9 +1,9 @@
 /// Returns the first element in a pair.
 ///
 /// ## Examples
-/// ```gleam
-/// first(tuple(1, 2)) == 1
-/// ```
+///    > first(tuple(1, 2))
+///    1
+///
 ///
 pub fn first(pair: tuple(a, b)) -> a {
   let tuple(a, _) = pair
@@ -13,9 +13,9 @@ pub fn first(pair: tuple(a, b)) -> a {
 /// Returns the second element in a pair.
 ///
 /// ## Examples
-/// ```gleam
-/// second(tuple(1, 2)) == 2
-/// ```
+///    > second(tuple(1, 2))
+///    2
+///
 ///
 pub fn second(pair: tuple(a, b)) -> b {
   let tuple(_, a) = pair
@@ -25,9 +25,9 @@ pub fn second(pair: tuple(a, b)) -> b {
 /// Returns a new pair with the elements swapped.
 ///
 /// ## Examples
-/// ```gleam
-/// swap(tuple(1, 2)) == tuple(2, 1)
-/// ```
+///    > swap(tuple(1, 2))
+///    tuple(2, 1)
+///
 ///
 pub fn swap(pair: tuple(a, b)) -> tuple(b, a) {
   let tuple(a, b) = pair
@@ -38,9 +38,9 @@ pub fn swap(pair: tuple(a, b)) -> tuple(b, a) {
 /// it.
 ///
 /// ## Examples
-/// ```gleam
-/// tuple(1, 2) |> map_first(fn(n) { n * 2 }) == 2
-/// ```
+///    > tuple(1, 2) |> map_first(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
@@ -51,9 +51,9 @@ pub fn map_first(of pair: tuple(a, b), with fun: fn(a) -> c) -> tuple(c, b) {
 /// it.
 ///
 /// ## Examples
-/// ```gleam
-/// tuple(1, 2) |> map_second(fn(n) { n * 2 }) == 4
-/// ```
+///    > tuple(1, 2) |> map_second(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
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index 2558e57..fac116c 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -94,9 +94,9 @@ pub fn unwrap(result: Result(a, e), or default: a) -> a {
 ///
 /// ## Examples
 ///
-/// ```
-/// none() == Error(Nil)
-/// ```
+///    > none()
+///    Error(Nil)
+///
 ///
 pub fn none() -> Option(a) {
   Error(Nil)
diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam
index 880ee6a..2b59f60 100644
--- a/src/gleam/string.gleam
+++ b/src/gleam/string.gleam
@@ -14,10 +14,12 @@ pub type String =
 /// Determine if a string is empty.
 ///
 /// ## Examples
-/// ```
-/// is_empty("") == True
-/// is_empty("the world") == False
-/// ```
+///    > is_empty("")
+///    True
+///
+///    > is_empty("the world")
+///    False
+///
 ///
 pub fn is_empty(str: String) -> Bool {
   str == ""
@@ -26,18 +28,18 @@ pub fn is_empty(str: String) -> Bool {
 /// Get the length of a
 ///
 /// ## Examples
-/// ```gleam
-/// length("") == 0
-/// ```
+///    > length("")
+///    0
+///
 ///
 pub external fn length(String) -> Int = "string" "length"
 
 /// Reverse a string.
 ///
 /// ## Examples
-/// ```gleam
-/// reverse("stressed") == "desserts"
-/// ```
+///    > reverse("stressed")
+///    "desserts"
+///
 ///
 pub fn reverse(string: String) -> String {
   string
@@ -49,10 +51,12 @@ pub fn reverse(string: String) -> String {
 /// Replace all occurrences of some substring.
 ///
 /// ## Examples
-/// ```gleam
-/// replace("Json.Decode.succeed", each: ".", with: "-") == "Json-Decode-succeed"
-/// replace("a,b,c,d,e", each: ",", with: "/")           == "a/b/c/d/e"
-/// ```
+///    > replace("Json.Decode.succeed", each: ".", with: "-")
+///    "Json-Decode-succeed"
+///
+///    > replace("a,b,c,d,e", each: ",", with: "/")
+///    "a/b/c/d/e"
+///
 ///
 pub fn replace(
   in string: String,
@@ -68,9 +72,9 @@ pub fn replace(
 /// Convert a string to all lower case. Useful for case-insensitive comparisons.
 ///
 /// ## Examples
-/// ```gleam
-/// lowercase("X-FILES") == "x-files"
-/// ```
+///    > lowercase("X-FILES")
+///    "x-files"
+///
 ///
 pub external fn lowercase(String) -> String = "string" "lowercase"
 
@@ -78,19 +82,21 @@ pub external fn lowercase(String) -> String = "string" "lowercase"
 /// and VIRTUAL YELLING.
 ///
 /// ## Examples
-/// ```gleam
-/// uppercase("skinner") == "SKINNER"
-/// ```
+///    > uppercase("skinner")
+///    "SKINNER"
+///
 ///
 pub external fn uppercase(String) -> String = "string" "uppercase"
 
 /// Determines the order of the two strings.
 ///
 /// ## Examples
-/// ```gleam
-/// compare("Anthony", "Anthony") == order.Eq
-/// compare("A", "B") == order.Gt
-/// ```
+///    > compare("Anthony", "Anthony")
+///    order.Eq
+///
+///    > compare("A", "B")
+///    order.Gt
+///
 ///
 pub external fn compare(String, String) -> order.Order =
   "gleam_stdlib" "compare_strings"
@@ -102,11 +108,15 @@ pub external fn compare(String, String) -> order.Order =
 /// are taken starting from the *end* of the list.
 ///
 /// ## Examples
-/// ```gleam
-/// slice("gleam", from: 1, to: 3) == "lea"
-/// slice("gleam", from: 1, to: 10) == "leam"
-/// slice("snakes on a plane!", from: -6, to: -1) == "plane"
-/// ```
+///    > slice("gleam", from: 1, to: 3)
+///    "lea"
+///
+///    > slice("gleam", from: 1, to: 10)
+///    "leam"
+///
+///    > slice("snakes on a plane!", from: -6, to: -1)
+///    "plane"
+///
 ///
 // pub fn slice(out_of string: String, from start: Int, end: Int) -> String {}
 
@@ -114,9 +124,9 @@ pub external fn compare(String, String) -> order.Order =
 /// Drop *n* Graphemes from the left side of a
 ///
 /// ## Examples
-/// ```gleam
-/// drop_left(from: "The Lone Gunmen", up_to: 2) == "e Lone Gunmen"
-/// ```
+///    > drop_left(from: "The Lone Gunmen", up_to: 2)
+///    "e Lone Gunmen"
+///
 ///
 // pub fn drop_left(from string: String, up_to num_graphemes: Int) -> String {}
 
@@ -124,9 +134,9 @@ pub external fn compare(String, String) -> order.Order =
 /// Drop *n* Graphemes from the right side of a
 ///
 /// ## Examples
-/// ```gleam
-/// drop_right(from: "Cigarette Smoking Man", up_to: 2) == "Cigarette Smoking M"
-/// ```
+///    > drop_right(from: "Cigarette Smoking Man", up_to: 2)
+///    "Cigarette Smoking M"
+///
 ///
 // pub fn drop_right(from string: String, up_to num_graphemes: Int) -> String {}
 
@@ -135,11 +145,15 @@ pub external fn compare(String, String) -> order.Order =
 /// Check if the first string contains the second.
 ///
 /// ## Examples
-/// ```gleam
-/// contains(does: "theory", contain: "ory") == True
-/// contains(does: "theory", contain: "the") == True
-/// contains(does: "theory", contain: "THE") == False
-/// ```
+///    > contains(does: "theory", contain: "ory")
+///    True
+///
+///    > contains(does: "theory", contain: "the")
+///    True
+///
+///    > contains(does: "theory", contain: "THE")
+///    False
+///
 ///
 external fn erl_contains(String, String) -> Bool =
   "gleam_stdlib" "string_contains"
@@ -153,9 +167,9 @@ pub fn contains(does haystack: String, contain needle: String) -> Bool {
 /// See if the second string starts with the first one.
 ///
 /// ## Examples
-/// ```gleam
-/// starts_with(does: "theory", start_with: "ory") == False
-/// ```
+///    > starts_with(does: "theory", start_with: "ory")
+///    False
+///
 ///
 // pub fn starts_with(does string: String, start_with prefix: String) -> String {}
 
@@ -164,9 +178,9 @@ pub fn contains(does haystack: String, contain needle: String) -> Bool {
 /// See if the second string ends with the first one.
 ///
 /// ## Examples
-/// ```gleam
-/// ends_with(does: "theory", end_with: "ory") == True
-/// ```
+///    > ends_with(does: "theory", end_with: "ory")
+///    True
+///
 ///
 // pub fn ends_with(does string: String, end_with suffix: String) -> String {}
 
@@ -175,9 +189,9 @@ pub fn contains(does haystack: String, contain needle: String) -> Bool {
 /// Split a string using a given separator.
 ///
 /// ## Examples
-/// ```gleam
-/// split("home/evan/Desktop/", on: "/") == ["home","evan","Desktop", ""]
-/// ```
+///    > split("home/evan/Desktop/", on: "/")
+///    ["home","evan","Desktop", ""]
+///
 ///
 pub fn split(x: String, on substring: String) -> List(String) {
   x
@@ -190,9 +204,9 @@ pub fn split(x: String, on substring: String) -> List(String) {
 /// Append two strings.
 ///
 /// ## Examples
-/// ```gleam
-/// append(to: "butter", suffix: "fly") == "butterfly"
-/// ```
+///    > append(to: "butter", suffix: "fly")
+///    "butterfly"
+///
 ///
 pub fn append(to first: String, suffix second: String) -> String {
   first
@@ -204,9 +218,9 @@ pub fn append(to first: String, suffix second: String) -> String {
 /// Concatenate many strings into one.
 ///
 /// ## Examples
-/// ```gleam
-/// concat(["never", "the", "less"]) == "nevertheless"
-/// ```
+///    > concat(["never", "the", "less"])
+///    "nevertheless"
+///
 ///
 pub fn concat(strings: List(String)) -> String {
   strings
@@ -217,9 +231,9 @@ pub fn concat(strings: List(String)) -> String {
 /// Repeat a string `n` times.
 ///
 /// ## Examples
-/// ```gleam
-/// repeat("ha", times: 3) == "hahaha"
-/// ```
+///    > repeat("ha", times: 3)
+///    "hahaha"
+///
 ///
 fn repeat_help(chunk: String, result: List(String), repeats: Int) -> String {
   case repeats <= 0 {
@@ -235,9 +249,9 @@ pub fn repeat(string: String, times times: Int) -> String {
 /// Join many strings together with a given separator.
 ///
 /// ## Examples
-/// ```gleam
-/// join(["home","evan","Desktop"], with: "/") == "home/evan/Desktop"
-/// ```
+///    > join(["home","evan","Desktop"], with: "/")
+///    "home/evan/Desktop"
+///
 ///
 pub fn join(strings: List(String), with separator: String) -> String {
   strings
@@ -252,11 +266,15 @@ pub fn join(strings: List(String), with separator: String) -> String {
 /// Pad a string on the left until it has at least given number of Graphemes.
 ///
 /// ## Examples
-/// ```gleam
-/// pad_left("121", to: 5, with: ".") == "..121"
-/// pad_left("121", to: 3, with: ".") == "121"
-/// pad_left("121", to: 2, with: ".") == "121"
-/// ```
+///    > pad_left("121", to: 5, with: ".")
+///    "..121"
+///
+///    > pad_left("121", to: 3, with: ".")
+///    "121"
+///
+///    > pad_left("121", to: 2, with: ".")
+///    "121"
+///
 ///
 // pub fn pad_left(string: String, to size: Int, with: String) {}
 
@@ -264,11 +282,15 @@ pub fn join(strings: List(String), with separator: String) -> String {
 /// Pad a string on the right until it has a given length.
 ///
 /// ## Examples
-/// ```gleam
-/// pad_right("121", to: 5, with: ".") == "121.."
-/// pad_right("121", to: 3, with: ".") == "121"
-/// pad_right("121", to: 2, with: ".") == "121"
-/// ```
+///    > pad_right("121", to: 5, with: ".")
+///    "121.."
+///
+///    > pad_right("121", to: 3, with: ".")
+///    "121"
+///
+///    > pad_right("121", to: 2, with: ".")
+///    "121"
+///
 ///
 // pub fn pad_right(string: String, to size: Int, with: String) {}
 
@@ -276,9 +298,9 @@ pub fn join(strings: List(String), with separator: String) -> String {
 /// Get rid of whitespace on both sides of a String.
 ///
 /// ## Examples
-/// ```gleam
-/// trim("  hats  \n") == "hats"
-/// ```
+///    > trim("  hats  \n")
+///    "hats"
+///
 ///
 // pub fn trim(string: String) -> String {}
 
@@ -286,9 +308,9 @@ pub fn join(strings: List(String), with separator: String) -> String {
 /// Get rid of whitespace on the left of a String.
 ///
 /// ## Examples
-/// ```gleam
-/// trim_left("  hats  \n") == "hats  \n"
-/// ```
+///    > trim_left("  hats  \n")
+///    "hats  \n"
+///
 ///
 // pub fn trim_left(string: String) -> String {}
 
@@ -296,9 +318,9 @@ pub fn join(strings: List(String), with separator: String) -> String {
 /// Get rid of whitespace on the right of a String.
 ///
 /// ## Examples
-/// ```gleam
-/// trim_right("  hats  \n") == "  hats"
-/// ```
+///    > trim_right("  hats  \n")
+///    "  hats"
+///
 ///
 // pub fn trim_right(string: String) -> String {}
 
@@ -310,7 +332,9 @@ pub fn join(strings: List(String), with separator: String) -> String {
 // TODO
 // /// Convert a string to a list of Graphemes.
 // ///
-// /// to_graphemes("abc") == ['a','b','c']
+// ///    > to_graphemes("abc")
+///    ['a','b','c']
+///
 // ///
 // pub fn to_graphemes(string: String) -> List(String) {}
 
@@ -319,7 +343,9 @@ pub fn join(strings: List(String), with separator: String) -> String {
 // /// want to create a string primarily by consing, perhaps for decoding
 // /// something.
 // ///
-// /// from_list(['a','b','c']) == "abc"
+// ///    > from_list(['a','b','c'])
+///    "abc"
+///
 // ///
 // // pub fn from_graphemes(graphemes: List(Grapheme)) -> String {}
 
@@ -328,8 +354,8 @@ pub fn join(strings: List(String), with separator: String) -> String {
 /// pattern match on strings exactly as you would with lists.
 ///
 /// ## Examples
-/// ```gleam
-/// next_grapheme("") == Error(Nil)
-/// ```
+///    > next_grapheme("")
+///    Error(Nil)
+///
 ///
 // pub fn next_grapheme(string: String) -> Option(tuple(Grapheme, String)) {}