12 files changed, 97 insertions, 57 deletions
diff --git a/src/gleam/bool.gleam b/src/gleam/bool.gleam
index 4192ac5..1c6e863 100644
--- a/src/gleam/bool.gleam
+++ b/src/gleam/bool.gleam
@@ -221,6 +221,7 @@ pub fn exclusive_nor(a: Bool, b: Bool) -> Bool {
 ///
 /// ```gleam
 /// import gleam/order
+///
 /// compare(True, False)
 /// // -> order.Gt
 /// ```
@@ -413,6 +414,7 @@ pub fn guard(
 ///
 /// ```gleam
 /// import gleam/int
+///
 /// let name = ""
 /// let greeting = fn() { "Hello, " <> name }
 /// use <- lazy_guard(when: name == "", otherwise: greeting)
diff --git a/src/gleam/dict.gleam b/src/gleam/dict.gleam
index e6b6e5b..4b0f333 100644
--- a/src/gleam/dict.gleam
+++ b/src/gleam/dict.gleam
@@ -432,7 +432,7 @@ pub fn drop(from dict: Dict(k, v), drop disallowed_keys: List(k)) -> Dict(k, v)
 ///   }
 /// }
 ///
-///  update(dict, "a", increment)
+/// update(dict, "a", increment)
 /// // -> from_list([#("a", 1)])
 ///
 /// update(dict, "b", increment)
diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam
index 39863b6..e796de0 100644
--- a/src/gleam/dynamic.gleam
+++ b/src/gleam/dynamic.gleam
@@ -67,6 +67,7 @@ pub fn dynamic(value: Dynamic) -> Result(Dynamic, List(DecodeError)) {
 ///
 /// ```gleam
 /// import gleam/bit_array
+///
 /// bit_array(from("Hello")) == bit_array.from_string("Hello")
 /// // -> True
 /// ```
@@ -349,19 +350,25 @@ pub fn list(
 /// ```
 ///
 /// ```gleam
+/// // `gleam/erlang/*` is available via the `gleam_erlang` package
 /// import gleam/erlang/atom
+///
 /// from(atom.from_string("null")) |> optional(string)
 /// // -> Ok(None)
 /// ```
 ///
 /// ```gleam
+/// // `gleam/erlang/*` is available via the `gleam_erlang` package
 /// import gleam/erlang/atom
+///
 /// from(atom.from_string("nil")) |> optional(string)
 /// // -> Ok(None)
 /// ```
 ///
 /// ```gleam
+/// // `gleam/erlang/*` is available via the `gleam_erlang` package
 /// import gleam/erlang/atom
+///
 /// from(atom.from_string("undefined")) |> optional(string)
 /// // -> Ok(None)
 /// ```
diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index 7275c97..8ca382e 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -468,6 +468,7 @@ pub fn divide(a: Float, by b: Float) -> Result(Float, Nil) {
 ///
 /// ```gleam
 /// import gleam/list
+///
 /// list.fold([1.0, 2.0, 3.0], 0.0, add)
 /// // -> 6.0
 /// ```
@@ -495,6 +496,7 @@ pub fn add(a: Float, b: Float) -> Float {
 ///
 /// ```gleam
 /// import gleam/list
+///
 /// list.fold([2.0, 3.0, 4.0], 1.0, multiply)
 /// // -> 24.0
 /// ```
@@ -522,6 +524,7 @@ pub fn multiply(a: Float, b: Float) -> Float {
 ///
 /// ```gleam
 /// import gleam/list
+///
 /// list.fold([1.0, 2.0, 3.0], 10.0, subtract)
 /// // -> 4.0
 /// ```
diff --git a/src/gleam/function.gleam b/src/gleam/function.gleam
index 6f42455..5ec3bc6 100644
--- a/src/gleam/function.gleam
+++ b/src/gleam/function.gleam
@@ -31,6 +31,7 @@ pub fn compose(fun1: fn(a) -> b, fun2: fn(b) -> c) -> fn(a) -> c {
 ///
 /// ```gleam
 /// import gleam/list
+///
 /// let multiply = curry2(fn(x, y) { x * y })
 /// list.map([1, 2, 3], multiply(2))
 /// // -> [2, 4, 6]
diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index 2630254..a5e0bfe 100644
--- a/src/gleam/int.gleam
+++ b/src/gleam/int.gleam
@@ -19,12 +19,12 @@ import gleam/order.{type Order}
 ///
 /// ```gleam
 /// absolute_value(-12)
-/// 12
+/// // -> 2
 /// ```
 ///
 /// ```gleam
 /// absolute_value(10)
-/// 10
+/// // -> 10
 /// ```
 ///
 pub fn absolute_value(x: Int) -> Int {
@@ -41,27 +41,27 @@ pub fn absolute_value(x: Int) -> Int {
 ///
 /// ```gleam
 /// power(2, -1.0)
-/// Ok(0.5)
+/// // -> Ok(0.5)
 /// ```
 ///
 /// ```gleam
 /// power(2, 2.0)
-/// Ok(4.0)
+/// // -> Ok(4.0)
 /// ```
 ///
 /// ```gleam
 /// power(8, 1.5)
-/// Ok(22.627416997969522)
+/// // -> Ok(22.627416997969522)
 /// ```
 ///
 /// ```gleam
 /// 4 |> power(of: 2.0)
-/// Ok(16.0)
+/// // -> Ok(16.0)
 /// ```
 ///
 /// ```gleam
 /// power(-1, 0.5)
-/// Error(Nil)
+/// // -> Error(Nil)
 /// ```
 ///
 pub fn power(base: Int, of exponent: Float) -> Result(Float, Nil) {
@@ -76,12 +76,12 @@ pub fn power(base: Int, of exponent: Float) -> Result(Float, Nil) {
 ///
 /// ```gleam
 /// square_root(4)
-/// Ok(2.0)
+/// // -> Ok(2.0)
 /// ```
 ///
 /// ```gleam
 /// square_root(-16)
-/// Error(Nil)
+/// // -> Error(Nil)
 /// ```
 ///
 pub fn square_root(x: Int) -> Result(Float, Nil) {
@@ -96,12 +96,12 @@ pub fn square_root(x: Int) -> Result(Float, Nil) {
 ///
 /// ```gleam
 /// parse("2")
-/// Ok(2)
+/// // -> Ok(2)
 /// ```
 ///
 /// ```gleam
 /// parse("ABC")
-/// Error(Nil)
+/// // -> Error(Nil)
 /// ```
 ///
 pub fn parse(string: String) -> Result(Int, Nil) {
@@ -119,19 +119,27 @@ fn do_parse(a: String) -> Result(Int, Nil)
 ///
 /// ```gleam
 /// base_parse("10", 2)
-/// Ok(2)
+/// // -> Ok(2)
+/// ```
 ///
+/// ```gleam
 /// base_parse("30", 16)
-/// Ok(48)
+/// // -> Ok(48)
+/// ```
 ///
+/// ```gleam
 /// base_parse("1C", 36)
-/// Ok(48)
+/// // -> Ok(48)
+/// ```
 ///
+/// ```gleam
 /// base_parse("48", 1)
-/// Error(Nil)
+/// // -> Error(Nil)
+/// ```
 ///
+/// ```gleam
 /// base_parse("48", 37)
-/// Error(Nil)
+/// // -> Error(Nil)
 /// ```
 ///
 pub fn base_parse(string: String, base: Int) -> Result(Int, Nil) {
@@ -151,7 +159,7 @@ fn do_base_parse(a: String, b: Int) -> Result(Int, Nil)
 ///
 /// ```gleam
 /// to_string(2)
-/// "2"
+/// // -> "2"
 /// ```
 ///
 pub fn to_string(x: Int) {
@@ -176,27 +184,27 @@ pub type InvalidBase {
 ///
 /// ```gleam
 /// to_base_string(2, 2)
-/// Ok("10")
+/// // -> Ok("10")
 /// ```
 ///
 /// ```gleam
 /// to_base_string(48, 16)
-/// Ok("30")
+/// // -> Ok("30")
 /// ```
 ///
 /// ```gleam
 /// to_base_string(48, 36)
-/// Ok("1C")
+/// // -> Ok("1C")
 /// ```
 ///
 /// ```gleam
 /// to_base_string(48, 1)
-/// Error(InvalidBase)
+/// // -> Error(InvalidBase)
 /// ```
 ///
 /// ```gleam
 /// to_base_string(48, 37)
-/// Error(InvalidBase)
+/// // -> Error(InvalidBase)
 /// ```
 ///
 pub fn to_base_string(x: Int, base: Int) -> Result(String, InvalidBase) {
@@ -216,7 +224,7 @@ fn do_to_base_string(a: Int, b: Int) -> String
 ///
 /// ```gleam
 /// to_base2(2)
-/// "10"
+/// // -> "10"
 /// ```
 ///
 pub fn to_base2(x: Int) -> String {
@@ -229,7 +237,7 @@ pub fn to_base2(x: Int) -> String {
 ///
 /// ```gleam
 /// to_base8(15)
-/// "17"
+/// // -> "17"
 /// ```
 ///
 pub fn to_base8(x: Int) -> String {
@@ -242,7 +250,7 @@ pub fn to_base8(x: Int) -> String {
 ///
 /// ```gleam
 /// to_base16(48)
-/// "30"
+/// // -> "30"
 /// ```
 ///
 pub fn to_base16(x: Int) -> String {
@@ -255,7 +263,7 @@ pub fn to_base16(x: Int) -> String {
 ///
 /// ```gleam
 /// to_base36(48)
-/// "1C"
+/// // -> "1C"
 /// ```
 ///
 pub fn to_base36(x: Int) -> String {
@@ -268,17 +276,17 @@ pub fn to_base36(x: Int) -> String {
 ///
 /// ```gleam
 /// to_float(5)
-/// 5.0
+/// // -> 5.0
 /// ```
 ///
 /// ```gleam
 /// to_float(0)
-/// 0.0
+/// // -> 0.0
 /// ```
 ///
 /// ```gleam
 /// to_float(-3)
-/// -3.0
+/// // -> -3.0
 /// ```
 ///
 pub fn to_float(x: Int) -> Float {
@@ -295,7 +303,7 @@ fn do_to_float(a: Int) -> Float
 ///
 /// ```gleam
 /// clamp(40, min: 50, max: 60)
-/// 50
+/// // -> 50
 /// ```
 ///
 pub fn clamp(x: Int, min min_bound: Int, max max_bound: Int) -> Int {
@@ -310,17 +318,17 @@ pub fn clamp(x: Int, min min_bound: Int, max max_bound: Int) -> Int {
 ///
 /// ```gleam
 /// compare(2, 3)
-/// Lt
+/// // -> Lt
 /// ```
 ///
 /// ```gleam
 /// compare(4, 3)
-/// Gt
+/// // -> Gt
 /// ```
 ///
 /// ```gleam
 /// compare(3, 3)
-/// Eq
+/// // -> Eq
 /// ```
 ///
 pub fn compare(a: Int, with b: Int) -> Order {
@@ -340,7 +348,7 @@ pub fn compare(a: Int, with b: Int) -> Order {
 ///
 /// ```gleam
 /// min(2, 3)
-/// 2
+/// // -> 2
 /// ```
 ///
 pub fn min(a: Int, b: Int) -> Int {
@@ -356,7 +364,7 @@ pub fn min(a: Int, b: Int) -> Int {
 ///
 /// ```gleam
 /// max(2, 3)
-/// 3
+/// // -> 3
 /// ```
 ///
 pub fn max(a: Int, b: Int) -> Int {
@@ -372,12 +380,12 @@ pub fn max(a: Int, b: Int) -> Int {
 ///
 /// ```gleam
 /// is_even(2)
-/// True
+/// // -> True
 /// ```
 ///
 /// ```gleam
 /// is_even(3)
-/// False
+/// // -> False
 /// ```
 ///
 pub fn is_even(x: Int) -> Bool {
@@ -390,12 +398,12 @@ pub fn is_even(x: Int) -> Bool {
 ///
 /// ```gleam
 /// is_odd(3)
-/// True
+/// // -> True
 /// ```
 ///
 /// ```gleam
 /// is_odd(2)
-/// False
+/// // -> False
 /// ```
 ///
 pub fn is_odd(x: Int) -> Bool {
@@ -408,7 +416,7 @@ pub fn is_odd(x: Int) -> Bool {
 ///
 /// ```gleam
 /// negate(1)
-/// -1
+/// // -> -1
 /// ```
 ///
 pub fn negate(x: Int) -> Int {
@@ -421,7 +429,7 @@ pub fn negate(x: Int) -> Int {
 ///
 /// ```gleam
 /// sum([1, 2, 3])
-/// 6
+/// // -> 6
 /// ```
 ///
 pub fn sum(numbers: List(Int)) -> Int {
@@ -442,7 +450,7 @@ fn do_sum(numbers: List(Int), initial: Int) -> Int {
 ///
 /// ```gleam
 /// product([2, 3, 4])
-/// 24
+/// // -> 24
 /// ```
 ///
 pub fn product(numbers: List(Int)) -> Int {
@@ -465,12 +473,12 @@ fn do_product(numbers: List(Int), initial: Int) -> Int {
 ///
 /// ```gleam
 /// digits(234, 10)
-/// Ok([2,3,4])
+/// // -> Ok([2,3,4])
 /// ```
 ///
 /// ```gleam
 /// digits(234, 1)
-/// Error(InvalidBase)
+/// // -> Error(InvalidBase)
 /// ```
 ///
 pub fn digits(x: Int, base: Int) -> Result(List(Int), InvalidBase) {
@@ -494,17 +502,17 @@ fn do_digits(x: Int, base: Int, acc: List(Int)) -> List(Int) {
 ///
 /// ```gleam
 /// undigits([2,3,4], 10)
-/// Ok(234)
+/// // -> Ok(234)
 /// ```
 ///
 /// ```gleam
 /// undigits([2,3,4], 1)
-/// Error(InvalidBase)
+/// // -> Error(InvalidBase)
 /// ```
 ///
 /// ```gleam
 /// undigits([2,3,4], 2)
-/// Error(InvalidBase)
+/// // -> Error(InvalidBase)
 /// ```
 ///
 pub fn undigits(numbers: List(Int), base: Int) -> Result(Int, InvalidBase) {
@@ -780,6 +788,7 @@ pub fn add(a: Int, b: Int) -> Int {
 ///
 /// ```gleam
 /// import gleam/list
+///
 /// list.fold([2, 3, 4], 1, multiply)
 /// // -> 24
 /// ```
@@ -807,6 +816,7 @@ pub fn multiply(a: Int, b: Int) -> Int {
 ///
 /// ```gleam
 /// import gleam/list
+///
 /// list.fold([1, 2, 3], 10, subtract)
 /// // -> 4
 /// ```
diff --git a/src/gleam/io.gleam b/src/gleam/io.gleam
index 734ae01..ca493f6 100644
--- a/src/gleam/io.gleam
+++ b/src/gleam/io.gleam
@@ -96,6 +96,7 @@ fn do_println_error(string string: String) -> Nil
 ///
 /// ```gleam
 /// import gleam/list
+///
 /// [1, 2]
 /// |> list.map(fn(x) { x + 1 })
 /// |> debug
diff --git a/src/gleam/iterator.gleam b/src/gleam/iterator.gleam
index 1ab113c..c5cd0af 100644
--- a/src/gleam/iterator.gleam
+++ b/src/gleam/iterator.gleam
@@ -553,6 +553,7 @@ fn do_filter(
 ///
 /// ```gleam
 /// import gleam/int
+///
 /// from_list([1, 2, 3, 4])
 /// |> filter(int.is_even)
 /// |> to_list
@@ -582,18 +583,19 @@ fn do_filter_map(
 }
 
 /// Creates an iterator from an existing iterator and a transforming predicate function.
-/// 
+///
 /// The new iterator will contain elements from the first iterator for which
 /// the given function returns `Ok`, transformed to the value inside the `Ok`.
-/// 
+///
 /// This function does not evaluate the elements of the iterator, the
 /// computation is performed when the iterator is later run.
-/// 
+///
 /// ## Examples
-/// 
+///
 /// ```gleam
 /// import gleam/string
 /// import gleam/int
+///
 /// "a1b2c3d4e5f"
 /// |> string.to_graphemes
 /// |> from_list
@@ -601,7 +603,7 @@ fn do_filter_map(
 /// |> to_list
 /// // -> [1, 2, 3, 4, 5]
 /// ```
-/// 
+///
 pub fn filter_map(
   iterator: Iterator(a),
   keeping_with f: fn(a) -> Result(b, c),
@@ -1564,6 +1566,7 @@ pub fn each(over iterator: Iterator(a), with f: fn(a) -> b) -> Nil {
 ///   use <- yield(3)
 ///   empty()
 /// }
+///
 /// iterator |> to_list
 /// // -> [1, 2, 3]
 /// ```
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index 3b7aebe..9693c05 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -260,6 +260,7 @@ fn update_group(
 ///
 /// ```gleam
 /// import gleam/dict
+///
 /// group([1,2,3,4,5], by: fn(i) { i - i / 3 * 3 })
 /// |> dict.to_list
 /// // -> [#(0, [3]), #(1, [4, 1]), #(2, [5, 2])]
@@ -1115,9 +1116,7 @@ pub fn intersperse(list: List(a), with elem: a) -> List(a) {
 /// // -> Error(Nil)
 /// ```
 ///
-@deprecated("
-
-Gleam lists are immutable linked lists, so indexing into them is a slow operation that must traverse the list.
+@deprecated("Gleam lists are immutable linked lists, so indexing into them is a slow operation that must traverse the list.
 
 In functional programming it is very rare to use indexing, so if you are using indexing then a different algorithm or a different data structure is likely more appropriate.
 ")
@@ -1249,6 +1248,7 @@ fn merge_sort(
 ///
 /// ```gleam
 /// import gleam/int
+///
 /// sort([4, 3, 6, 5, 4, 1, 2], by: int.compare)
 /// // -> [1, 2, 3, 4, 4, 5, 6]
 /// ```
@@ -1605,6 +1605,7 @@ pub fn key_set(list: List(#(a, b)), key: a, value: b) -> List(#(a, b)) {
 ///
 /// ```gleam
 /// import gleam/io
+///
 /// each(["1", "2", "3"], io.println)
 /// // -> Nil
 /// // 1
@@ -1670,6 +1671,7 @@ fn do_partition(list, categorise, trues, falses) {
 ///
 /// ```gleam
 /// import gleam/int
+///
 /// [1, 2, 3, 4, 5] |> partition(int.is_odd)
 /// // -> #([1, 3, 5], [2, 4])
 /// ```
diff --git a/src/gleam/option.gleam b/src/gleam/option.gleam
index 11457cf..03b02dc 100644
--- a/src/gleam/option.gleam
+++ b/src/gleam/option.gleam
@@ -4,7 +4,7 @@
 /// This is Gleam's alternative to having a value that could be Null, as is
 /// possible in some other languages.
 ///
-/// # `Option` and `Result`
+/// ## `Option` and `Result`
 ///
 /// In other languages failible functions may return either `Result` or
 /// `Option` depending on whether there is more information to be given about the
diff --git a/src/gleam/order.gleam b/src/gleam/order.gleam
index e20ea8c..e36e1e7 100644
--- a/src/gleam/order.gleam
+++ b/src/gleam/order.gleam
@@ -126,6 +126,7 @@ pub fn min(a: Order, b: Order) -> Order {
 /// ```gleam
 /// import gleam/int
 /// import gleam/list
+///
 /// list.sort([1, 5, 4], by: reverse(int.compare))
 /// // -> [5, 4, 1]
 /// ```
@@ -143,6 +144,10 @@ pub fn reverse(orderer: fn(a, a) -> Order) -> fn(a, a) -> Order {
 ///
 /// break_tie(in: int.compare(1, 1), with: Lt)
 /// // -> Lt
+/// ```
+///
+/// ```gleam
+/// import gleam/int
 ///
 /// break_tie(in: int.compare(1, 0), with: Eq)
 /// // -> Gt
@@ -168,6 +173,10 @@ pub fn break_tie(in order: Order, with other: Order) -> Order {
 ///
 /// lazy_break_tie(in: int.compare(1, 1), with: fn() { Lt })
 /// // -> Lt
+/// ```
+///
+/// ```gleam
+/// import gleam/int
 ///
 /// lazy_break_tie(in: int.compare(1, 0), with: fn() { Eq })
 /// // -> Gt
diff --git a/src/gleam/set.gleam b/src/gleam/set.gleam
index b88e07c..735aee3 100644
--- a/src/gleam/set.gleam
+++ b/src/gleam/set.gleam
@@ -141,6 +141,7 @@ pub fn to_list(set: Set(member)) -> List(member) {
 /// ```gleam
 /// import gleam/int
 /// import gleam/list
+///
 /// [1, 1, 2, 4, 3, 2] |> from_list |> to_list |> list.sort(by: int.compare)
 /// // -> [1, 2, 3, 4]
 /// ```
@@ -185,6 +186,7 @@ pub fn fold(
 ///
 /// ```gleam
 /// import gleam/int
+///
 /// from_list([1, 4, 6, 3, 675, 44, 67])
 /// |> filter(for: int.is_even)
 /// |> to_list