format docblocks

13 files changed, 66 insertions, 93 deletions

diff --git a/src/gleam/bool.gleam b/src/gleam/bool.gleam
index 05092f5..a7b04e1 100644
--- a/src/gleam/bool.gleam
+++ b/src/gleam/bool.gleam
@@ -10,9 +10,9 @@ import gleam/order.{Order}
 
 /// Returns the and of two bools, but it evaluates both arguments.
 ///
-/// It's the function equivalent of the `&&` operator. 
+/// It's the function equivalent of the `&&` operator.
 /// This function is useful in higher order functions or pipes.
-/// 
+///
 /// ## Examples
 ///
 /// ```gleam
@@ -25,15 +25,16 @@ import gleam/order.{Order}
 /// > False |> and(True)
 /// False
 /// ```
+///
 pub fn and(a: Bool, b: Bool) -> Bool {
   a && b
 }
 
 /// Returns the or of two bools, but it evaluates both arguments.
 ///
-/// It's the function equivalent of the `||` operator. 
+/// It's the function equivalent of the `||` operator.
 /// This function is useful in higher order functions or pipes.
-/// 
+///
 /// ## Examples
 ///
 /// ```gleam
@@ -46,6 +47,7 @@ pub fn and(a: Bool, b: Bool) -> Bool {
 /// > False |> or(True)
 /// True
 /// ```
+///
 pub fn or(a: Bool, b: Bool) -> Bool {
   a || b
 }
diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam
index bf6c3a5..9830310 100644
--- a/src/gleam/dynamic.gleam
+++ b/src/gleam/dynamic.gleam
@@ -962,9 +962,7 @@ pub fn decode2(
 /// > from(#(1, 2.0, "3"))
 /// > |> decode3(MyRecord, element(0, int), element(1, float), element(2, string))
 /// Ok(MyRecord(1, 2.0, "3"))
-/// ```
 ///
-/// ```gleam
 /// > from(#("", "", ""))
 /// > |> decode3(MyRecord, element(0, int), element(1, float), element(2, string))
 /// Error([
@@ -1002,9 +1000,7 @@ pub fn decode3(
 /// >   element(3, string),
 /// > )
 /// Ok(MyRecord(1, 2.1, "3", "4"))
-/// ```
 ///
-/// ```gleam
 /// > from(#("", "", "", ""))
 /// > |> decode4(
 /// >   MyRecord,
@@ -1055,9 +1051,7 @@ pub fn decode4(
 /// >   element(4, string),
 /// > )
 /// Ok(MyRecord(1, 2.1, "3", "4", "5"))
-/// ```
 ///
-/// ```gleam
 /// > from(#("", "", "", "", ""))
 /// > |> decode5(
 /// >   MyRecord,
@@ -1112,9 +1106,7 @@ pub fn decode5(
 /// >   element(5, string),
 /// > )
 /// Ok(MyRecord(1, 2.1, "3", "4", "5", "6"))
-/// ```
 ///
-/// ```gleam
 /// > from(#("", "", "", "", "", ""))
 /// > |> decode6(
 /// >   MyRecord,
@@ -1174,9 +1166,7 @@ pub fn decode6(
 /// >   element(6, string),
 /// > )
 /// Ok(MyRecord(1, 2.1, "3", "4", "5", "6", "7"))
-/// ```
 ///
-/// ```gleam
 /// > from(#("", "", "", "", "", "", ""))
 /// > |> decode7(
 /// >   MyRecord,
@@ -1240,9 +1230,7 @@ pub fn decode7(
 /// >   element(7, string),
 /// > )
 /// Ok(MyRecord(1, 2.1, "3", "4", "5", "6", "7", "8"))
-/// ```
 ///
-/// ```gleam
 /// > from(#("", "", "", "", "", "", "", ""))
 /// > |> decode7(
 /// >   MyRecord,
@@ -1310,9 +1298,7 @@ pub fn decode8(
 /// >   element(8, string),
 /// > )
 /// Ok(MyRecord(1, 2.1, "3", "4", "5", "6", "7", "8", "9"))
-/// ```
 ///
-/// ```gleam
 /// > from(#("", "", "", "", "", "", "", "", ""))
 /// > |> decode7(
 /// >   MyRecord,
diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index 3f6e0de..4507483 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -52,7 +52,7 @@ if javascript {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > clamp(1.2, min: 1.4, max: 1.6)
 /// 1.4
 /// ```
@@ -66,6 +66,7 @@ pub fn clamp(x: Float, min min_bound: Float, max max_bound: Float) -> Float {
 /// Compares two `Float`s, returning an order.
 ///
 /// ## Examples
+///
 /// ```gleam
 /// > compare(2.0, 2.3)
 /// Lt
@@ -282,10 +283,10 @@ pub fn absolute_value(x: Float) -> Float {
 pub fn power(base: Float, of exponent: Float) -> Result(Float, Nil) {
   let fractional: Bool = ceiling(exponent) -. exponent >. 0.
   // In the following check:
-  // 1. If the base is negative and the exponent is fractional then 
+  // 1. If the base is negative and the exponent is fractional then
   //    return an error as it will otherwise be an imaginary number
   // 2. If the base is 0 and the exponent is negative then the expression
-  //    is equivalent to the exponent divided by 0 and an error should be 
+  //    is equivalent to the exponent divided by 0 and an error should be
   //    returned
   case base <. 0. && fractional || base == 0. && exponent <. 0. {
     True -> Error(Nil)
@@ -376,8 +377,8 @@ fn do_product(numbers: List(Float), initial: Float) -> Float {
   }
 }
 
-/// Returns 0.0 if boundary_a and boundary_b are equal,
-/// otherwise returns a Float x where: lower_boundary =< x < upper_boundary.
+/// Returns `0.0` if `boundary_a` and `boundary_b` are equal,
+/// otherwise returns a `Float x` where `lower_boundary =< x < upper_boundary`.
 ///
 /// ## Examples
 ///
@@ -439,9 +440,9 @@ pub fn divide(a: Float, by b: Float) -> Result(Float, Nil) {
 
 /// Adds two floats together.
 ///
-/// It's the function equivalent of the `+.` operator. 
+/// It's the function equivalent of the `+.` operator.
 /// This function is useful in higher order functions or pipes.
-/// 
+///
 /// ## Examples
 ///
 /// ```gleam
@@ -454,15 +455,16 @@ pub fn divide(a: Float, by b: Float) -> Result(Float, Nil) {
 /// > 3.0 |> add(2.0)
 /// 5.0
 /// ```
+///
 pub fn add(a: Float, b: Float) -> Float {
   a +. b
 }
 
 /// Multiplies two floats together.
 ///
-/// It's the function equivalent of the `*.` operator. 
+/// It's the function equivalent of the `*.` operator.
 /// This function is useful in higher order functions or pipes.
-/// 
+///
 /// ## Examples
 ///
 /// ```gleam
@@ -475,15 +477,16 @@ pub fn add(a: Float, b: Float) -> Float {
 /// > 3.0 |> multiply(2.0)
 /// 6.0
 /// ```
+///
 pub fn multiply(a: Float, b: Float) -> Float {
   a *. b
 }
 
 /// Subtracts one float from another.
 ///
-/// It's the function equivalent of the `-.` operator. 
+/// It's the function equivalent of the `-.` operator.
 /// This function is useful in higher order functions or pipes.
-/// 
+///
 /// ## Examples
 ///
 /// ```gleam
@@ -499,6 +502,7 @@ pub fn multiply(a: Float, b: Float) -> Float {
 /// > 3.0 |> subtract(2.0, _)
 /// -1.0
 /// ```
+///
 pub fn subtract(a: Float, b: Float) -> Float {
   a -. b
 }
diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index d8ccf6e..58572fd 100644
--- a/src/gleam/int.gleam
+++ b/src/gleam/int.gleam
@@ -217,7 +217,7 @@ pub fn to_base36(x: Int) -> String {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > to_float(5)
 /// 5.
 ///
@@ -246,7 +246,7 @@ if javascript {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > clamp(40, min: 50, max: 60)
 /// 50
 /// ```
@@ -465,8 +465,8 @@ fn do_undigits(
   }
 }
 
-/// Returns 0 if boundary_a and boundary_b are equal,
-/// otherwise returns an Int x where: lower_boundary =< x < upper_boundary.
+/// Returns `0` if `boundary_a` and `boundary_b` are equal,
+/// otherwise returns an `Int x` where `lower_boundary =< x < upper_boundary`.
 ///
 /// ## Examples
 ///
@@ -655,9 +655,9 @@ pub fn floor_divide(dividend: Int, by divisor: Int) -> Result(Int, Nil) {
 
 /// Adds two integers together.
 ///
-/// It's the function equivalent of the `+` operator. 
+/// It's the function equivalent of the `+` operator.
 /// This function is useful in higher order functions or pipes.
-/// 
+///
 /// ## Examples
 ///
 /// ```gleam
@@ -670,15 +670,16 @@ pub fn floor_divide(dividend: Int, by divisor: Int) -> Result(Int, Nil) {
 /// > 3 |> add(2)
 /// 5
 /// ```
+///
 pub fn add(a: Int, b: Int) -> Int {
   a + b
 }
 
 /// Multiplies two integers together.
 ///
-/// It's the function equivalent of the `*` operator. 
+/// It's the function equivalent of the `*` operator.
 /// This function is useful in higher order functions or pipes.
-/// 
+///
 /// ## Examples
 ///
 /// ```gleam
@@ -691,15 +692,16 @@ pub fn add(a: Int, b: Int) -> Int {
 /// > 3 |> multiply(2)
 /// 6
 /// ```
+///
 pub fn multiply(a: Int, b: Int) -> Int {
   a * b
 }
 
 /// Subtracts one int from another.
 ///
-/// It's the function equivalent of the `-` operator. 
+/// It's the function equivalent of the `-` operator.
 /// This function is useful in higher order functions or pipes.
-/// 
+///
 /// ## Examples
 ///
 /// ```gleam
@@ -715,6 +717,7 @@ pub fn multiply(a: Int, b: Int) -> Int {
 /// > 3 |> subtract(2, _)
 /// -1
 /// ```
+///
 pub fn subtract(a: Int, b: Int) -> Int {
   a - b
 }
diff --git a/src/gleam/io.gleam b/src/gleam/io.gleam
index 3e4fadb..7a4da2a 100644
--- a/src/gleam/io.gleam
+++ b/src/gleam/io.gleam
@@ -6,7 +6,7 @@ import gleam/string
 ///
 /// ## Example
 ///
-/// ```
+/// ```gleam
 /// > io.print("Hi mum")
 /// // -> Hi mum
 /// Nil
diff --git a/src/gleam/iterator.gleam b/src/gleam/iterator.gleam
index 6290b05..83112fa 100644
--- a/src/gleam/iterator.gleam
+++ b/src/gleam/iterator.gleam
@@ -178,7 +178,7 @@ pub fn run(iterator: Iterator(e)) -> Nil {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > [1, 2, 3] |> from_list |> map(fn(x) { x * 2 }) |> to_list
 /// [2, 4, 6]
 /// ```
@@ -655,8 +655,8 @@ fn do_scan(
 ///
 /// ## Examples
 ///
-/// Generate a sequence of partial sums:
 /// ```gleam
+/// // Generate a sequence of partial sums
 /// > from_list([1, 2, 3, 4, 5]) |> scan(from: 0, with: fn(acc, el) { acc + el }) |> to_list
 /// [1, 3, 6, 10, 15]
 /// ```
@@ -1055,8 +1055,10 @@ pub fn empty() -> Iterator(element) {
 ///
 /// ## Examples
 ///
+/// ```gleam
 /// > once(fn() { 1 }) |> to_list
 /// [1]
+/// ```
 ///
 pub fn once(f: fn() -> element) -> Iterator(element) {
   fn() { Continue(f(), stop) }
@@ -1204,7 +1206,7 @@ pub fn try_fold(
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > from_list([1, 2, 3]) |> first
 /// Ok(1)
 ///
@@ -1226,7 +1228,7 @@ pub fn first(from iterator: Iterator(e)) -> Result(e, Nil) {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > from_list([1, 2, 3, 4]) |> at(2)
 /// Ok(3)
 ///
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index 362156b..c001677 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -1734,8 +1734,8 @@ pub fn last(list: List(a)) -> Result(a, Nil) {
 /// > combinations([1, 2, 3], 2)
 /// [[1, 2], [1, 3], [2, 3]]
 ///
-///  > combinations([1, 2, 3, 4], 3)
-///  [[1, 2, 3], [1, 2, 4], [1, 3, 4], [2, 3, 4]]
+/// > combinations([1, 2, 3, 4], 3)
+/// [[1, 2, 3], [1, 2, 4], [1, 3, 4], [2, 3, 4]]
 /// ```
 ///
 pub fn combinations(items: List(a), by n: Int) -> List(List(a)) {
diff --git a/src/gleam/map.gleam b/src/gleam/map.gleam
index 6c25a7c..327b446 100644
--- a/src/gleam/map.gleam
+++ b/src/gleam/map.gleam
@@ -34,7 +34,6 @@ pub external type Map(key, value)
 /// 1
 /// ```
 ///
-///
 pub fn size(map: Map(k, v)) -> Int {
   do_size(map)
 }
@@ -211,7 +210,6 @@ if javascript {
 /// [#(3, 9), #(2, 8)]
 /// ```
 ///
-///
 pub fn map_values(in map: Map(k, v), with fun: fn(k, v) -> w) -> Map(k, w) {
   do_map_values(fun, map)
 }
diff --git a/src/gleam/option.gleam b/src/gleam/option.gleam
index 8af678f..e4d4bbf 100644
--- a/src/gleam/option.gleam
+++ b/src/gleam/option.gleam
@@ -17,7 +17,7 @@ pub type Option(a) {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > all([Some(1), Some(2)])
 /// Some([1, 2])
 ///
@@ -77,6 +77,7 @@ pub fn is_none(option: Option(a)) -> Bool {
 /// ```gleam
 /// > to_result(Some(1), "some_error")
 /// Ok(1)
+///
 /// > to_result(None, "some_error")
 /// Error("some_error")
 /// ```
@@ -95,6 +96,7 @@ pub fn to_result(option: Option(a), e) -> Result(a, e) {
 /// ```gleam
 /// > from_result(Ok(1))
 /// Some(1)
+///
 /// > from_result(Error("some_error"))
 /// None
 /// ```
@@ -277,7 +279,7 @@ pub fn lazy_or(first: Option(a), second: fn() -> Option(a)) -> Option(a) {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > values([Some(1), None, Some(3)])
 /// [1, 3]
 /// ```
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index 150de35..5c226ef 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -156,9 +156,7 @@ pub fn then(
 /// ```gleam
 /// > unwrap(Ok(1), 0)
 /// 1
-/// ```
 ///
-/// ```gleam
 /// > unwrap(Error(""), 0)
 /// 0
 /// ```
@@ -178,9 +176,7 @@ pub fn unwrap(result: Result(a, e), or default: a) -> a {
 /// ```gleam
 /// > lazy_unwrap(Ok(1), fn() { 0 })
 /// 1
-/// ```
 ///
-/// ```gleam
 /// > lazy_unwrap(Error(""), fn() { 0 })
 /// 0
 /// ```
@@ -200,9 +196,7 @@ pub fn lazy_unwrap(result: Result(a, e), or default: fn() -> a) -> a {
 /// ```gleam
 /// > unwrap_error(Error(1), 0)
 /// 1
-/// ```
 ///
-/// ```gleam
 /// > unwrap_error(Ok(""), 0)
 /// 0
 /// ```
@@ -222,9 +216,7 @@ pub fn unwrap_error(result: Result(a, e), or default: e) -> e {
 /// ```gleam
 /// > unwrap_both(Error(1))
 /// 1
-/// ```
 ///
-/// ```gleam
 /// > unwrap_both(Ok(2))
 /// 2
 /// ```
@@ -314,9 +306,7 @@ pub fn lazy_or(
 /// ```gleam
 /// > all([Ok(1), Ok(2)])
 /// Ok([1, 2])
-/// ```
 ///
-/// ```gleam
 /// > all([Ok(1), Error("e")])
 /// Error("e")
 /// ```
@@ -332,9 +322,7 @@ pub fn all(results: List(Result(a, e))) -> Result(List(a), e) {
 /// ```gleam
 /// > replace(Ok(1), Nil)
 /// Ok(Nil)
-/// ```
 ///
-/// ```gleam
 /// > replace(Error(1), Nil)
 /// Error(1)
 /// ```
@@ -353,9 +341,7 @@ pub fn replace(result: Result(a, e), value: b) -> Result(b, e) {
 /// ```gleam
 /// > replace_error(Error(1), Nil)
 /// Error(Nil)
-/// ```
 ///
-/// ```gleam
 /// > replace_error(Ok(1), Nil)
 /// Ok(1)
 /// ```
@@ -371,7 +357,7 @@ pub fn replace_error(result: Result(a, e1), error: e2) -> Result(a, e2) {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > values([Ok(1), None, Ok(3)])
 /// [1, 3]
 /// ```
diff --git a/src/gleam/set.gleam b/src/gleam/set.gleam
index d221282..39836ea 100644
--- a/src/gleam/set.gleam
+++ b/src/gleam/set.gleam
@@ -214,8 +214,8 @@ fn order(first: Set(member), second: Set(member)) -> #(Set(member), Set(member))
 /// ## Examples
 ///
 /// ```gleam
-///  > union(from_list([1, 2]), from_list([2, 3])) |> to_list
-///  [1, 2, 3]
+/// > union(from_list([1, 2]), from_list([2, 3])) |> to_list
+/// [1, 2, 3]
 /// ```
 ///
 pub fn union(of first: Set(member), and second: Set(member)) -> Set(member) {
@@ -230,8 +230,8 @@ pub fn union(of first: Set(member), and second: Set(member)) -> Set(member) {
 /// ## Examples
 ///
 /// ```gleam
-///  > intersection(from_list([1, 2]), from_list([2, 3])) |> to_list
-///  [2]
+/// > intersection(from_list([1, 2]), from_list([2, 3])) |> to_list
+/// [2]
 /// ```
 ///
 pub fn intersection(
diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam
index 598868a..a9a47ae 100644
--- a/src/gleam/string.gleam
+++ b/src/gleam/string.gleam
@@ -208,6 +208,7 @@ if javascript {
 /// are taken starting from the *end* of the list.
 ///
 /// ## Examples
+///
 /// ```gleam
 /// > slice(from: "gleam", at_index: 1, length: 2)
 /// "le"
@@ -261,6 +262,7 @@ if javascript {
 /// If the `from` string does not contain the `before` string, `from` is returned unchanged.
 ///
 /// ## Examples
+///
 /// ```gleam
 /// > crop(from: "The Lone Gunmen", before: "Lone")
 /// "Lone Gunmen"
@@ -290,6 +292,7 @@ if javascript {
 /// Drops *n* graphemes from the left side of a `String`.
 ///
 /// ## Examples
+///
 /// ```gleam
 /// > drop_left(from: "The Lone Gunmen", up_to: 2)
 /// "e Lone Gunmen"
@@ -305,6 +308,7 @@ pub fn drop_left(from string: String, up_to num_graphemes: Int) -> String {
 /// Drops *n* graphemes from the right side of a `String`.
 ///
 /// ## Examples
+///
 /// ```gleam
 /// > drop_right(from: "Cigarette Smoking Man", up_to: 2)
 /// "Cigarette Smoking M"
@@ -755,9 +759,7 @@ pub fn utf_codepoint(value: Int) -> Result(UtfCodepoint, Nil) {
 /// ```gleam
 /// > to_option("")
 /// None
-/// ```
 ///
-/// ```gleam
 /// > to_option("hats")
 /// Some("hats")
 /// ```
@@ -778,9 +780,7 @@ pub fn to_option(s: String) -> Option(String) {
 /// ```gleam
 /// > first("")
 /// Error(Nil)
-/// ```
 ///
-/// ```gleam
 /// > first("icecream")
 /// Ok("i")
 /// ```
@@ -801,9 +801,7 @@ pub fn first(s: String) -> Result(String, Nil) {
 /// ```gleam
 /// > last("")
 /// Error(Nil)
-/// ```
 ///
-/// ```gleam
 /// > last("icecream")
 /// Ok("m")
 /// ```
@@ -833,7 +831,7 @@ pub fn capitalise(s: String) -> String {
   }
 }
 
-/// Returns a `String` representation of values in Gleam syntax.
+/// Returns a `String` representation of a term in Gleam syntax.
 ///
 pub fn inspect(term: anything) -> String {
   do_inspect(term)
diff --git a/src/gleam/uri.gleam b/src/gleam/uri.gleam
index be14668..80fc806 100644
--- a/src/gleam/uri.gleam
+++ b/src/gleam/uri.gleam
@@ -4,7 +4,7 @@
 //// URIs or encoding query strings). The functions in this module are implemented
 //// according to [RFC 3986](https://tools.ietf.org/html/rfc3986).
 ////
-//// Query encoding (Form encoding) is defined in the 
+//// Query encoding (Form encoding) is defined in the
 //// [W3C specification](https://www.w3.org/TR/html52/sec-forms.html#urlencoded-form-data).
 
 import gleam/int
@@ -41,9 +41,8 @@ pub type Uri {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > parse("https://example.com:1234/a/b?query=true#fragment")
-///
 /// Ok(Uri(scheme: Some("https"), ...))
 /// ```
 ///
@@ -190,9 +189,8 @@ if javascript {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > parse_query("a=1&b=2")
-///
 /// Ok([#("a", "1"), #("b", "2")])
 /// ```
 ///
@@ -216,9 +214,8 @@ if javascript {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > query_to_string([#("a", "1"), #("b", "2")])
-///
 /// "a=1&b=2"
 /// ```
 ///
@@ -242,9 +239,8 @@ fn query_pair(pair: #(String, String)) -> StringBuilder {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > percent_encode("100% great")
-///
 /// "100%25%20great"
 /// ```
 ///
@@ -266,9 +262,8 @@ if javascript {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > percent_decode("100%25+great")
-///
 /// Ok("100% great")
 /// ```
 ///
@@ -316,9 +311,8 @@ fn remove_dot_segments(input: List(String)) -> List(String) {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > path_segments("/users/1")
-///
 /// ["users" ,"1"]
 /// ```
 ///
@@ -332,10 +326,9 @@ pub fn path_segments(path: String) -> List(String) {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > let uri = Uri(Some("http"), None, Some("example.com"), ...)
 /// > to_string(uri)
-///
 /// "https://example.com"
 /// ```
 ///
@@ -377,10 +370,9 @@ pub fn to_string(uri: Uri) -> String {
 ///
 /// ## Examples
 ///
-/// ```
+/// ```gleam
 /// > assert Ok(uri) = parse("http://example.com/path?foo#bar")
 /// > origin(uri)
-///
 /// Ok("http://example.com")
 /// ```
 ///