19 files changed, 183 insertions, 198 deletions

diff --git a/src/gleam/base.gleam b/src/gleam/base.gleam
index 6807767..5134cc0 100644
--- a/src/gleam/base.gleam
+++ b/src/gleam/base.gleam
@@ -2,6 +2,7 @@ import gleam/bit_string
 import gleam/string
 
 /// Encodes a BitString into a base 64 encoded string.
+///
 pub fn encode64(input: BitString, padding: Bool) -> String {
   let encoded = do_encode64(input)
   case padding {
@@ -20,7 +21,8 @@ if javascript {
     "../gleam_stdlib.js" "encode64"
 }
 
-/// Decodes a base 64 encoded string into a BitString.
+/// Decodes a base 64 encoded string into a `BitString`.
+///
 pub fn decode64(encoded: String) -> Result(BitString, Nil) {
   let padded = case bit_string.byte_size(bit_string.from_string(encoded)) % 4 {
     0 -> encoded
@@ -39,14 +41,16 @@ if javascript {
     "../gleam_stdlib.js" "decode64"
 }
 
-/// Encodes a BitString into a base 64 encoded string with URL and filename safe alphabet.
+/// Encodes a `BitString` into a base 64 encoded string with URL and filename safe alphabet.
+///
 pub fn url_encode64(input: BitString, padding: Bool) -> String {
   encode64(input, padding)
   |> string.replace("+", "-")
   |> string.replace("/", "_")
 }
 
-/// Decodes a base 64 encoded string with URL and filename safe alphabet into a BitString.
+/// Decodes a base 64 encoded string with URL and filename safe alphabet into a `BitString`.
+///
 pub fn url_decode64(encoded: String) -> Result(BitString, Nil) {
   encoded
   |> string.replace("-", "+")
diff --git a/src/gleam/bit_builder.gleam b/src/gleam/bit_builder.gleam
index fc8ec64..90f8866 100644
--- a/src/gleam/bit_builder.gleam
+++ b/src/gleam/bit_builder.gleam
@@ -1,40 +1,26 @@
+//// BitBuilder is a type used for efficiently concatenating bits to create bit
+//// strings.
+////
+//// If we append one bit string to another the bit strings must be copied to a
+//// new location in memory so that they can sit together. This behaviour
+//// enables efficient reading of the string but copying can be expensive,
+//// especially if we want to join many bit strings together.
+////
+//// BitBuilder is different in that it can be joined together in constant
+//// time using minimal memory, and then can be efficiently converted to a
+//// bit string using the `to_bit_string` function.
+////
+//// On Erlang this type is compatible with Erlang's iolists.
+
 import gleam/string_builder.{StringBuilder}
 import gleam/bit_string
 import gleam/list
 
 if erlang {
-  /// BitBuilder is a type used for efficiently concatenating bits to create bit
-  /// strings.
-  ///
-  /// If we append one bit string to another the bit strings must be copied to a
-  /// new location in memory so that they can sit together. This behaviour
-  /// enables efficient reading of the string but copying can be expensive,
-  /// especially if we want to join many bit strings together.
-  ///
-  /// BitBuilder is different in that it can be joined together in constant
-  /// time using minimal memory, and then can be efficiently converted to a
-  /// bit string using the `to_bit_string` function.
-  ///
-  /// On Erlang this type is compatible with Erlang's iolists.
-  ///
   pub external type BitBuilder
 }
 
 if javascript {
-  /// BitBuilder is a type used for efficiently concatenating bits to create bit
-  /// strings.
-  ///
-  /// If we append one bit string to another the bit strings must be copied to a
-  /// new location in memory so that they can sit together. This behaviour
-  /// enables efficient reading of the string but copying can be expensive,
-  /// especially if we want to join many bit strings together.
-  ///
-  /// BitBuilder is different in that it can be joined together in constant
-  /// time using minimal memory, and then can be efficiently converted to a
-  /// bit string using the `to_bit_string` function.
-  ///
-  /// On Erlang this type is compatible with Erlang's iolists.
-  ///
   pub opaque type BitBuilder {
     Bits(BitString)
     Text(StringBuilder)
diff --git a/src/gleam/bit_string.gleam b/src/gleam/bit_string.gleam
index 448a7cb..a30b40d 100644
--- a/src/gleam/bit_string.gleam
+++ b/src/gleam/bit_string.gleam
@@ -1,8 +1,8 @@
 //// Working with raw bit string data.
-//// The BitString type should be used instead of a String type when not utf8
+//// The `BitString` type should be used instead of a String type when not utf8
 //// encoded.
 
-/// Converts a UTF-8 String type into a raw BitString type.
+/// Converts a UTF-8 `String` type into a raw `BitString` type.
 ///
 pub fn from_string(x: String) -> BitString {
   do_from_string(x)
diff --git a/src/gleam/bool.gleam b/src/gleam/bool.gleam
index 93d76d5..92706bf 100644
--- a/src/gleam/bool.gleam
+++ b/src/gleam/bool.gleam
@@ -1,10 +1,10 @@
-//// A type with two possible values, True and False. Used to indicate whether
+//// A type with two possible values, `True` and `False`. Used to indicate whether
 //// things are... true or false!
 ////
 //// Often is it clearer and offers more type safety to define a custom type
-//// than to use Bool. For example, rather than having a `is_teacher: Bool`
-//// field consider having a `role: SchoolRole` field where SchoolRole is a custom
-//// type that can be either Student or Teacher.
+//// than to use `Bool`. For example, rather than having a `is_teacher: Bool`
+//// field consider having a `role: SchoolRole` field where `SchoolRole` is a custom
+//// type that can be either `Student` or `Teacher`.
 
 import gleam/order.{Order}
 
@@ -27,7 +27,7 @@ pub fn negate(bool: Bool) -> Bool {
   }
 }
 
-/// Returns the nor of two bools
+/// Returns the nor of two bools.
 ///
 /// ## Examples
 ///
@@ -52,7 +52,7 @@ pub fn nor(a: Bool, b: Bool) -> Bool {
   }
 }
 
-/// Returns the nand of two bools
+/// Returns the nand of two bools.
 ///
 /// ## Examples
 ///
@@ -77,7 +77,7 @@ pub fn nand(a: Bool, b: Bool) -> Bool {
   }
 }
 
-/// Returns the exclusive or of two bools
+/// Returns the exclusive or of two bools.
 ///
 /// ## Examples
 ///
@@ -102,7 +102,7 @@ pub fn exclusive_or(a: Bool, b: Bool) -> Bool {
   }
 }
 
-/// Returns the exclusive nor of two bools
+/// Returns the exclusive nor of two bools.
 ///
 /// ## Examples
 ///
@@ -127,7 +127,7 @@ pub fn exclusive_nor(a: Bool, b: Bool) -> Bool {
   }
 }
 
-/// Compares two bools and returns the first values Order to the second.
+/// Compares two bools and returns the first value's `Order` to the second.
 ///
 /// ## Examples
 ///
@@ -144,7 +144,7 @@ pub fn compare(a: Bool, with b: Bool) -> Order {
   }
 }
 
-/// Returns True if either bool value is True.
+/// Returns `True` if either argument's value is `True`.
 ///
 /// ## Examples
 ///
@@ -164,7 +164,7 @@ pub fn max(a: Bool, b: Bool) -> Bool {
   }
 }
 
-/// Returns False if either bool value is False.
+/// Returns `False` if either bool value is `False`.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam
index 2b6d3b1..d48bd24 100644
--- a/src/gleam/dynamic.gleam
+++ b/src/gleam/dynamic.gleam
@@ -58,7 +58,7 @@ if javascript {
     "../gleam_stdlib.js" "identity"
 }
 
-/// Checks to see whether a Dynamic value is a bit_string, and return the bit_string if
+/// Checks to see whether a `Dynamic` value is a bit_string, and returns that bit string if
 /// it is.
 ///
 /// ## Examples
@@ -83,7 +83,7 @@ if javascript {
     "../gleam_stdlib.js" "decode_bit_string"
 }
 
-/// Checks to see whether a Dynamic value is a string, and return the string if
+/// Checks to see whether a `Dynamic` value is a string, and returns that string if
 /// it is.
 ///
 /// ## Examples
@@ -137,7 +137,7 @@ if javascript {
     "../gleam_stdlib.js" "classify_dynamic"
 }
 
-/// Checks to see whether a Dynamic value is an int, and return the int if it
+/// Checks to see whether a `Dynamic` value is an int, and returns that int if it
 /// is.
 ///
 /// ## Examples
@@ -162,7 +162,7 @@ if javascript {
     "../gleam_stdlib.js" "decode_int"
 }
 
-/// Checks to see whether a Dynamic value is an float, and return the float if
+/// Checks to see whether a `Dynamic` value is a float, and returns that float if
 /// it is.
 ///
 /// ## Examples
@@ -187,7 +187,7 @@ if javascript {
     "../gleam_stdlib.js" "decode_float"
 }
 
-/// Checks to see whether a Dynamic value is an bool, and return the bool if
+/// Checks to see whether a `Dynamic` value is a bool, and returns that bool if
 /// it is.
 ///
 /// ## Examples
@@ -212,7 +212,7 @@ if javascript {
     "../gleam_stdlib.js" "decode_bool"
 }
 
-/// Checks to see whether a Dynamic value is a list, and return the list if it
+/// Checks to see whether a `Dynamic` value is a list, and returns that list if it
 /// is.
 ///
 /// If you wish to decode all the elements in the list use the `typed_list`
@@ -240,7 +240,7 @@ if javascript {
     "../gleam_stdlib.js" "decode_list"
 }
 
-/// Checks to see whether a Dynamic value is a result, and return the result if
+/// Checks to see whether a `Dynamic` value is a result, and returns that result if
 /// it is.
 ///
 /// ## Examples
@@ -270,8 +270,8 @@ if javascript {
     "../gleam_stdlib.js" "decode_result"
 }
 
-/// Checks to see whether a Dynamic value is a result of a particular type, and
-/// return the result if it is
+/// Checks to see whether a `Dynamic` value is a result of a particular type, and
+/// returns that result if it is.
 ///
 /// The `ok` and `error` arguments are decoders for decoding the `Ok` and
 /// `Error` values of the result.
@@ -306,8 +306,8 @@ pub fn typed_result(
   }
 }
 
-/// Checks to see whether a Dynamic value is a list of a particular type, and
-/// return the list if it is.
+/// Checks to see whether a `Dynamic` value is a list of a particular type, and
+/// returns that list if it is.
 ///
 /// The second argument is a decoder function used to decode the elements of
 /// the list. The list is only decoded if all elements in the list can be
@@ -336,8 +336,8 @@ pub fn typed_list(
   |> result.then(list.try_map(_, decoder_type))
 }
 
-/// Checks to see if a Dynamic value is a nullable version of a particular
-/// type, and return the Option if it is.
+/// Checks to see if a `Dynamic` value is a nullable version of a particular
+/// type, and returns a corresponding `Option` if it is.
 ///
 /// ## Examples
 ///
@@ -382,8 +382,8 @@ if javascript {
     "../gleam_stdlib.js" "decode_option"
 }
 
-/// Checks to see if a Dynamic value is a map with a specific field, and return
-/// the value of the field if it is.
+/// Checks to see if a `Dynamic` value is a map with a specific field, and returns
+/// the value of that field if it is.
 ///
 /// This will not succeed on a record.
 ///
@@ -410,8 +410,8 @@ if javascript {
     "../gleam_stdlib.js" "decode_field"
 }
 
-/// Checks to see if the Dynamic value is a tuple large enough to have a certain
-/// index, and return the value of that index if it is.
+/// Checks to see if a `Dynamic` value is a tuple large enough to have a certain
+/// index, and returns the value of that index if it is.
 ///
 /// ## Examples
 ///
@@ -496,7 +496,7 @@ if javascript {
     "../gleam_stdlib.js" "length"
 }
 
-/// Checks to see if the Dynamic value is a 2 element tuple.
+/// Checks to see if a `Dynamic` value is a 2-element tuple.
 ///
 /// If you do not wish to decode all the elements in the tuple use the
 /// `typed_tuple2` function instead.
@@ -544,7 +544,7 @@ fn put_expected(
   }
 }
 
-/// Checks to see if the Dynamic value is a 2 element tuple containing two
+/// Checks to see if a `Dynamic` value is a 2 element tuple containing
 /// specifically typed elements.
 ///
 /// If you wish to decode all the elements in the list use the `typed_tuple2`
@@ -575,7 +575,7 @@ pub fn typed_tuple2(
   Ok(#(a, b))
 }
 
-/// Checks to see if the Dynamic value is a 3 element tuple.
+/// Checks to see if the `Dynamic` value is a 3-element tuple.
 ///
 /// If you do not wish to decode all the elements in the tuple use the
 /// `typed_tuple3` function instead.
@@ -598,7 +598,7 @@ pub fn tuple3(
   Ok(unsafe_coerce(value))
 }
 
-/// Checks to see if the Dynamic value is a 3 element tuple containing two
+/// Checks to see if a `Dynamic` value is a 3-element tuple containing
 /// specifically typed elements.
 ///
 /// If you wish to decode all the elements in the list use the `typed_tuple3`
@@ -631,7 +631,7 @@ pub fn typed_tuple3(
   Ok(#(a, b, c))
 }
 
-/// Checks to see if the Dynamic value is a 4 element tuple.
+/// Checks to see if a `Dynamic` value is a 4-element tuple.
 ///
 /// If you do not wish to decode all the elements in the tuple use the
 /// `typed_tuple4` function instead.
@@ -654,7 +654,7 @@ pub fn tuple4(
   Ok(unsafe_coerce(value))
 }
 
-/// Checks to see if the Dynamic value is a 4 element tuple containing two
+/// Checks to see if a `Dynamic` value is a 4 element tuple containing
 /// specifically typed elements.
 ///
 /// If you wish to decode all the elements in the list use the `typed_tuple4`
@@ -690,7 +690,7 @@ pub fn typed_tuple4(
   Ok(#(a, b, c, d))
 }
 
-/// Checks to see if the Dynamic value is a 5 element tuple.
+/// Checks to see if a `Dynamic` value is a 5-element tuple.
 ///
 /// If you do not wish to decode all the elements in the tuple use the
 /// `typed_tuple5` function instead.
@@ -713,7 +713,7 @@ pub fn tuple5(
   Ok(unsafe_coerce(value))
 }
 
-/// Checks to see if the Dynamic value is a 5 element tuple containing two
+/// Checks to see if a `Dynamic` value is a 5-element tuple containing
 /// specifically typed elements.
 ///
 /// If you wish to decode all the elements in the list use the `typed_tuple5`
@@ -750,7 +750,7 @@ pub fn typed_tuple5(
   Ok(#(a, b, c, d, e))
 }
 
-/// Checks to see if the Dynamic value is a 6 element tuple.
+/// Checks to see if a `Dynamic` value is a 6-element tuple.
 ///
 /// If you do not wish to decode all the elements in the tuple use the
 /// `typed_tuple6` function instead.
@@ -776,7 +776,7 @@ pub fn tuple6(
   Ok(unsafe_coerce(value))
 }
 
-/// Checks to see if the Dynamic value is a 6 element tuple containing two
+/// Checks to see if a `Dynamic` value is a 6-element tuple containing
 /// specifically typed elements.
 ///
 /// If you wish to decode all the elements in the list use the `typed_tuple6`
@@ -815,7 +815,7 @@ pub fn typed_tuple6(
   Ok(#(a, b, c, d, e, f))
 }
 
-/// Checks to see if the Dynamic value is map.
+/// Checks to see if a `Dynamic` value is a map.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index 43229c4..1d6eb6e 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -37,7 +37,7 @@ pub fn to_string(f: Float) -> String {
   |> string_builder.to_string
 }
 
-/// Restricts a Float between a lower and upper bound
+/// Restricts a float between a lower and upper bound.
 ///
 /// ## Examples
 ///
@@ -170,7 +170,7 @@ if javascript {
     "../gleam_stdlib.js" "round"
 }
 
-/// Returns the value as an int, truncating all decimal digits.
+/// Returns the value as an integer, truncating all decimal digits.
 ///
 /// ## Examples
 ///
@@ -250,7 +250,7 @@ pub fn square_root(number: Float) -> Result(Float, Nil) {
   }
 }
 
-/// Returns the negative of the value provided
+/// Returns the negative of the value provided.
 ///
 /// ## Examples
 ///
@@ -261,7 +261,7 @@ pub fn negate(x: Float) -> Float {
   -1. *. x
 }
 
-/// Sums a list of Floats.
+/// Sums a list of floats.
 ///
 /// ## Example
 ///
@@ -280,7 +280,7 @@ fn do_sum(numbers: List(Float), initial: Float) -> Float {
   }
 }
 
-/// Multiplies a list of Floats and returns the product.
+/// Multiplies a list of floats and returns the product.
 ///
 /// ## Example
 ///
diff --git a/src/gleam/function.gleam b/src/gleam/function.gleam
index 8010639..a6d2063 100644
--- a/src/gleam/function.gleam
+++ b/src/gleam/function.gleam
@@ -7,14 +7,14 @@ pub fn compose(fun1: fn(a) -> b, fun2: fn(b) -> c) -> fn(a) -> c {
 
 /// Takes a function with arity two
 /// and returns a curried equivalent.
-/// fn(a, b) -> c becomes fn(a) -> fn(b) -> c
+/// `fn(a, b) -> c` becomes `fn(a) -> fn(b) -> c`.
 pub fn curry2(fun: fn(a, b) -> value) {
   fn(a) { fn(b) { fun(a, b) } }
 }
 
 /// Takes a function with arity three
 /// and returns a curried equivalent.
-/// fn(a, b, c) -> d becomes fn(a) -> fn(b) -> fn(c) -> d
+/// `fn(a, b, c) -> d` becomes `fn(a) -> fn(b) -> fn(c) -> d`.
 pub fn curry3(fun: fn(a, b, c) -> value) {
   fn(a) { fn(b) { fn(c) { fun(a, b, c) } } }
 }
diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index 6c280d6..756e0eb 100644
--- a/src/gleam/int.gleam
+++ b/src/gleam/int.gleam
@@ -62,14 +62,14 @@ if javascript {
     "../gleam_stdlib.js" "to_string"
 }
 
-/// For use in to_base_string when base is outside of the allowed range.
+/// For use in `to_base_string` when base is outside of the allowed range.
 pub type InvalidBase {
   InvalidBase
 }
 
 /// Prints a given int to a string using the base number provided.
-/// Supports only bases 2 to 36, for values outside of which this function returns an Error(InvalidBase).
-/// For common bases (2, 8, 16, 36), use the to_baseN functions.
+/// Supports only bases 2 to 36, for values outside of which this function returns an `Error(InvalidBase)`.
+/// For common bases (2, 8, 16, 36), use the `to_baseN` functions.
 ///
 /// ## Examples
 ///
@@ -149,7 +149,7 @@ pub fn to_base36(int) {
   do_to_base_string(int, 36)
 }
 
-/// Takes an int and returns its value as a float
+/// Takes an int and returns its value as a float.
 ///
 /// ## Examples
 ///
@@ -176,7 +176,7 @@ if javascript {
     "../gleam_stdlib.js" "identity"
 }
 
-/// Restricts an Int between a lower and upper bound
+/// Restricts an int between a lower and upper bound.
 ///
 /// ## Examples
 ///
@@ -215,7 +215,7 @@ pub fn compare(a: Int, with b: Int) -> Order {
   }
 }
 
-/// Compares two int, returning the smaller of the two.
+/// Compares two ints, returning the smaller of the two.
 ///
 /// ## Examples
 ///
@@ -229,7 +229,7 @@ pub fn min(a: Int, b: Int) -> Int {
   }
 }
 
-/// Compares two int, returning the larger of the two.
+/// Compares two ints, returning the larger of the two.
 ///
 /// ## Examples
 ///
@@ -271,7 +271,7 @@ pub fn is_odd(x: Int) -> Bool {
   x % 2 != 0
 }
 
-/// Returns the negative of the value provided
+/// Returns the negative of the value provided.
 ///
 /// ## Examples
 ///
@@ -282,7 +282,7 @@ pub fn negate(x: Int) -> Int {
   -1 * x
 }
 
-/// Sums a list of Ints.
+/// Sums a list of ints.
 ///
 /// ## Example
 ///
@@ -301,7 +301,7 @@ fn do_sum(numbers: List(Int), initial: Int) -> Int {
   }
 }
 
-/// Multiplies a list of Ints and returns the product.
+/// Multiplies a list of ints and returns the product.
 ///
 /// ## Example
 ///
diff --git a/src/gleam/iterator.gleam b/src/gleam/iterator.gleam
index babebc6..3c250c3 100644
--- a/src/gleam/iterator.gleam
+++ b/src/gleam/iterator.gleam
@@ -1089,7 +1089,7 @@ fn do_try_fold(
 /// A variant of fold that might fail.
 /// 
 ///
-/// The folding function should return `Result(accumulator, error)
+/// The folding function should return `Result(accumulator, error)`.
 /// If the returned value is `Ok(accumulator)` try_fold will try the next value in the iterator.
 /// If the returned value is `Error(error)` try_fold will stop and return that error.
 ///
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index 5c46417..dadd9d9 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -179,7 +179,7 @@ pub fn first(list: List(a)) -> Result(a, Nil) {
   }
 }
 
-/// Gets the list minus the first element. If the list is empty `Error(Nil)` is
+/// Returns the list minus the first element. If the list is empty, `Error(Nil)` is
 /// returned.
 ///
 /// This function runs in constant time and does not make a copy of the list.
@@ -281,7 +281,7 @@ pub fn map(list: List(a), with fun: fn(a) -> b) -> List(b) {
   do_map(list, fun, [])
 }
 
-/// Similar to map but also lets you pass around an accumulated value.
+/// Similar to `map` but also lets you pass around an accumulated value.
 ///
 /// ## Examples
 ///
@@ -356,8 +356,8 @@ fn do_try_map(
   }
 }
 
-/// Takes a function that returns a Result applies it to each element in a
-/// given list in tern.
+/// Takes a function that returns a `Result` and applies it to each element in a
+/// given list in turn.
 ///
 /// If the function returns `Ok(new_value)` for all elements in the list then a
 /// list of the new values is returned.
@@ -595,7 +595,7 @@ pub fn index_fold(
 
 /// A variant of fold that might fail.
 ///
-/// The folding function should return `Result(accumulator, error)
+/// The folding function should return `Result(accumulator, error)`.
 /// If the returned value is `Ok(accumulator)` try_fold will try the next value in the list.
 /// If the returned value is `Error(error)` try_fold will stop and return that error.
 ///
@@ -632,7 +632,7 @@ pub type ContinueOrStop(a) {
 
 /// A variant of fold that allows to stop folding earlier.
 ///
-/// The folding function should return `ContinueOrStop(accumulator)
+/// The folding function should return `ContinueOrStop(accumulator)`.
 /// If the returned value is `Continue(accumulator)` fold_until will try the next value in the list.
 /// If the returned value is `Stop(accumulator)` fold_until will stop and return that accumulator.
 ///
@@ -664,10 +664,9 @@ pub fn fold_until(
 }
 
 /// Finds the first element in a given list for which the given function returns
-/// True.
+/// `True`.
 ///
-/// Returns `Error(Nil)` if no the function does not return True for any of the
-/// elements.
+/// Returns `Error(Nil)` if no such element is found.
 ///
 /// ## Examples
 ///
@@ -695,10 +694,9 @@ pub fn find(
 }
 
 /// Finds the first element in a given list for which the given function returns
-/// `Ok(new_value)` and return the new value for that element.
+/// `Ok(new_value)`, then returns the wrapped `new_value`.
 ///
-/// Returns `Error(Nil)` if no the function does not return Ok for any of the
-/// elements.
+/// Returns `Error(Nil)` if no such element is found.
 ///
 /// ## Examples
 ///
@@ -725,9 +723,9 @@ 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.
+/// 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
 ///
@@ -747,9 +745,9 @@ 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.
+/// 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
 ///
@@ -781,7 +779,7 @@ fn do_zip(xs: List(a), ys: List(b), acc: List(#(a, b))) -> List(#(a, b)) {
 
 /// 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
+/// If one of the lists is longer than the other, the remaining elements from
 /// the longer list are not used.
 ///
 /// ## Examples
@@ -804,7 +802,7 @@ pub fn zip(xs: List(a), ys: List(b)) -> List(#(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.
+/// If one of the lists is longer than the other, an `Error` is returned.
 ///
 /// ## Examples
 ///
@@ -880,7 +878,7 @@ pub fn intersperse(list: List(a), with elem: a) -> List(a) {
 /// Returns 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.
+/// `Error(Nil)` is returned if the list is not long enough for the given index.
 ///
 /// For any `index` less than 0 this function behaves as if it was set to 0.
 ///
@@ -1048,9 +1046,9 @@ fn do_split_while(
 }
 
 /// Splits a list in two before the first element that a given function returns
-/// False for.
+/// `False` for.
 ///
-/// If the function returns True for all elements the first list will be the
+/// If the function returns `True` for all elements the first list will be the
 /// input list, and the second list will be empty.
 ///
 /// ## Examples
@@ -1116,8 +1114,7 @@ fn do_pop(haystack, predicate, checked) {
 
 /// Removes the first element in a given list for which the predicate funtion returns `True`.
 ///
-/// Returns `Error(Nil)` if no the function does not return True for any of the
-/// elements.
+/// Returns `Error(Nil)` if no such element is found.
 ///
 /// ## Examples
 ///
@@ -1149,10 +1146,9 @@ fn do_pop_map(haystack, mapper, checked) {
 }
 
 /// Removes the first element in a given list for which the given function returns
-/// `Ok(new_value)` and return the new value as well as list with the value removed.
+/// `Ok(new_value)`, then returns the wrapped `new_value` as well as list with the value removed.
 ///
-/// Returns `Error(Nil)` if no the function does not return Ok for any of the
-/// elements.
+/// Returns `Error(Nil)` if no such element is found.
 ///
 /// ## Examples
 ///
@@ -1257,8 +1253,8 @@ pub fn partition(
   do_partition(list, categorise, [], [])
 }
 
-/// Returns all the permutations of a list
-/// All values must be unique
+/// Returns all the permutations of a list.
+/// All values must be unique.
 ///
 /// ## Examples
 ///
@@ -1290,7 +1286,7 @@ fn do_window(acc: List(List(a)), l: List(a), n: Int) -> List(List(a)) {
   }
 }
 
-/// Returns a list of sliding window
+/// Returns a list of sliding windows.
 ///
 /// ## Examples
 ///
@@ -1307,7 +1303,7 @@ pub fn window(l: List(a), by n: Int) -> List(List(a)) {
   |> reverse
 }
 
-/// Returns a list of tuples containing two contiguous elements
+/// Returns a list of tuples containing two contiguous elements.
 ///
 /// ## Examples
 ///
@@ -1461,10 +1457,10 @@ pub fn sized_chunk(in list: List(a), into count: Int) -> List(List(a)) {
 ///
 /// ## Examples
 ///
-///    > [] |> reduce(fn(x, y) { x + y })
+///    > [] |> reduce(fn(acc, x) { acc + x })
 ///    Error(Nil)
 ///
-///    > [1, 2, 3, 4, 5] |> reduce(fn(acc, i) { acc + i })
+///    > [1, 2, 3, 4, 5] |> reduce(fn(acc, x) { acc + x })
 ///    Ok(15)
 ///
 pub fn reduce(over list: List(a), with fun: fn(a, a) -> a) -> Result(a, Nil) {
diff --git a/src/gleam/map.gleam b/src/gleam/map.gleam
index e39f727..41decf1 100644
--- a/src/gleam/map.gleam
+++ b/src/gleam/map.gleam
@@ -136,7 +136,7 @@ if javascript {
 /// Fetches a value from a map for a given key.
 ///
 /// The map may not have a value for the key, so the value is wrapped in a
-/// Result.
+/// `Result`.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/option.gleam b/src/gleam/option.gleam
index 2baeaed..daab337 100644
--- a/src/gleam/option.gleam
+++ b/src/gleam/option.gleam
@@ -1,7 +1,7 @@
 import gleam/list
 
-/// Option represents a value that may be present or not. Some means the value is
-/// present, None means the value is not.
+/// `Option` represents a value that may be present or not. `Some` means the value is
+/// present, `None` means the value is not.
 ///
 /// This is Gleam's alternative to having a value that could be Null, as is
 /// possible in some other languages.
@@ -12,8 +12,8 @@ pub type Option(a) {
 }
 
 /// Combines a list of options into a single option.
-/// If all elements in the list are Some then returns a Some holding the list of values.
-/// If any element is None then returns None.
+/// If all elements in the list are `Some` then returns a `Some` holding the list of values.
+/// If any element is `None` then returns`None`.
 ///
 /// ## Examples
 ///
@@ -38,7 +38,7 @@ pub fn all(list: List(Option(a))) -> Option(List(a)) {
   )
 }
 
-/// Checks whether the option is a Some value.
+/// Checks whether the option is a `Some` value.
 ///
 /// ## Examples
 ///
@@ -52,7 +52,7 @@ pub fn is_some(option: Option(a)) -> Bool {
   option != None
 }
 
-/// Checks whether the option is a None value.
+/// Checks whether the option is a `None` value.
 ///
 /// ## Examples
 ///
@@ -66,7 +66,7 @@ pub fn is_none(option: Option(a)) -> Bool {
   option == None
 }
 
-/// Converts an Option type to a Result type
+/// Converts an `Option` type to a `Result` type.
 ///
 /// ## Examples
 ///
@@ -82,7 +82,7 @@ pub fn to_result(option: Option(a), e) -> Result(a, e) {
   }
 }
 
-/// Converts a Result type to an Option type
+/// Converts a `Result` type to an `Option` type.
 ///
 /// ## Examples
 ///
@@ -115,10 +115,10 @@ pub fn unwrap(option: Option(a), or default: a) -> a {
   }
 }
 
-/// Updates a value held within the Some of an Option by calling a given function
+/// Updates a value held within the `Some` of an Option by calling a given function
 /// on it.
 ///
-/// If the option is a None rather than Some the function is not called and the
+/// If the option is a `None` rather than `Some`, the function is not called and the
 /// option stays the same.
 ///
 /// ## Examples
@@ -136,7 +136,7 @@ pub fn map(over option: Option(a), with fun: fn(a) -> b) -> Option(b) {
   }
 }
 
-/// Merges a nested Option into a single layer.
+/// Merges a nested `Option` into a single layer.
 ///
 /// ## Examples
 ///
@@ -156,15 +156,15 @@ pub fn flatten(option: Option(Option(a))) -> Option(a) {
   }
 }
 
-/// Updates a value held within the Some of an Option by calling a given function
-/// on it, where the given function also returns an Option. The two Options are
-/// then merged together into one Option.
+/// Updates a value held within the `Some` of an `Option` by calling a given function
+/// on it, where the given function also returns an `Option`. The two options are
+/// then merged together into one `Option`.
 ///
-/// If the Option is a None rather than Some the function is not called and the
-/// Option stays the same.
+/// If the `Option` is a `None` rather than `Some` the function is not called and the
+/// option stays the same.
 ///
 /// This function is the equivalent of calling `map` followed by `flatten`, and
-/// it is useful for chaining together multiple functions that return Options.
+/// it is useful for chaining together multiple functions that return `Option`.
 ///
 /// ## Examples
 ///
@@ -187,7 +187,7 @@ pub fn then(option: Option(a), apply fun: fn(a) -> Option(b)) -> Option(b) {
   }
 }
 
-/// Returns the first value if it is Some, otherwise return the second value.
+/// Returns the first value if it is `Some`, otherwise returns the second value.
 ///
 /// ## Examples
 ///
@@ -210,8 +210,8 @@ pub fn or(first: Option(a), second: Option(a)) -> Option(a) {
   }
 }
 
-/// Given a list of options
-/// Return only the values inside Some
+/// Given a list of options,
+/// returns only the values inside `Some`.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/order.gleam b/src/gleam/order.gleam
index c030db4..9b75384 100644
--- a/src/gleam/order.gleam
+++ b/src/gleam/order.gleam
@@ -55,7 +55,7 @@ pub fn to_int(order: Order) -> Int {
   }
 }
 
-/// Compares two Order values to one another, producing a new Order.
+/// Compares two `Order` values to one another, producing a new `Order`.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/regex.gleam b/src/gleam/regex.gleam
index cd717d9..99d8dd6 100644
--- a/src/gleam/regex.gleam
+++ b/src/gleam/regex.gleam
@@ -13,7 +13,7 @@ pub type Match {
   Match(
     /// The full string of the match.
     content: String,
-    /// A Regex can have subpatterns, sup-parts that are in parentheses.
+    /// A `Regex` can have subpatterns, sup-parts that are in parentheses.
     submatches: List(Option(String)),
   )
 }
@@ -34,7 +34,7 @@ pub type Options {
   Options(case_insensitive: Bool, multi_line: Bool)
 }
 
-/// Creates a Regex with some additional options.
+/// Creates a `Regex` with some additional options.
 ///
 /// ## Examples
 ///
@@ -65,7 +65,7 @@ if javascript {
     "../gleam_stdlib.js" "compile_regex"
 }
 
-/// Creates a new Regex.
+/// Creates a new `Regex`.
 ///
 /// ## Examples
 ///
@@ -113,7 +113,7 @@ if javascript {
     "../gleam_stdlib.js" "regex_check"
 }
 
-/// Splits a string
+/// Splits a string.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index 1d0893d..9c25c85 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -3,7 +3,7 @@
 
 import gleam/list
 
-/// Checks whether the result is an Ok value.
+/// Checks whether the result is an `Ok` value.
 ///
 /// ## Examples
 ///
@@ -20,7 +20,7 @@ pub fn is_ok(result: Result(a, e)) -> Bool {
   }
 }
 
-/// Checks whether the result is an Error value.
+/// Checks whether the result is an `Error` value.
 ///
 /// ## Examples
 ///
@@ -37,10 +37,10 @@ pub fn is_error(result: Result(a, e)) -> Bool {
   }
 }
 
-/// Updates a value held within the Ok of a result by calling a given function
+/// Updates a value held within the `Ok` of a result by calling a given function
 /// on it.
 ///
-/// If the result is an Error rather than OK the function is not called and the
+/// If the result is an `Error` rather than `Ok` the function is not called and the
 /// result stays the same.
 ///
 /// ## Examples
@@ -58,10 +58,10 @@ pub fn map(over result: Result(a, e), with fun: fn(a) -> b) -> Result(b, e) {
   }
 }
 
-/// Updates a value held within the Error of a result by calling a given function
+/// Updates a value held within the `Error` of a result by calling a given function
 /// on it.
 ///
-/// If the result is Ok rather than Error the function is not called and the
+/// If the result is `Ok` rather than `Error` the function is not called and the
 /// result stays the same.
 ///
 /// ## Examples
@@ -82,7 +82,7 @@ pub fn map_error(
   }
 }
 
-/// Merges a nested Result into a single layer.
+/// Merges a nested `Result` into a single layer.
 ///
 /// ## Examples
 ///
@@ -102,11 +102,11 @@ pub fn flatten(result: Result(Result(a, e), e)) -> Result(a, e) {
   }
 }
 
-/// Updates a value held within the Ok of a result by calling a given function
+/// Updates a value held within the `Ok` of a result by calling a given function
 /// on it, where the given function also returns a result. The two results are
 /// then merged together into one result.
 ///
-/// If the result is an Error rather than OK the function is not called and the
+/// If the result is an `Error` rather than `Ok` the function is not called and the
 /// result stays the same.
 ///
 /// This function is the equivalent of calling `map` followed by `flatten`, and
@@ -136,8 +136,8 @@ pub fn then(
   }
 }
 
-/// Extracts the Ok value from a result, returning a default value if the result
-/// is an Error.
+/// Extracts the `Ok` value from a result, returning a default value if the result
+/// is an `Error`.
 ///
 /// ## Examples
 ///
@@ -154,8 +154,8 @@ pub fn unwrap(result: Result(a, e), or default: a) -> a {
   }
 }
 
-/// Extracts the Ok value from a result, evaluating the default function if the result
-/// is an Error.
+/// Extracts the `Ok` value from a result, evaluating the default function if the result
+/// is an `Error`.
 ///
 /// ## Examples
 ///
@@ -172,7 +172,7 @@ pub fn lazy_unwrap(result: Result(a, e), or default: fn() -> a) -> a {
   }
 }
 
-/// Transforms any error into Error(Nil)
+/// Transforms any error into `Error(Nil)`.
 ///
 /// ## Examples
 ///
@@ -186,7 +186,7 @@ pub fn nil_error(result: Result(a, e)) -> Result(a, Nil) {
   map_error(result, fn(_) { Nil })
 }
 
-/// Returns the first value if it is Ok, otherwise return the second value.
+/// Returns the first value if it is `Ok`, otherwise returns the second value.
 ///
 /// ## Examples
 ///
@@ -209,7 +209,7 @@ pub fn or(first: Result(a, e), second: Result(a, e)) -> Result(a, e) {
   }
 }
 
-/// Returns the first value if it is Ok, otherwise evaluates the given function for a fallback value.
+/// Returns the first value if it is `Ok`, otherwise evaluates the given function for a fallback value.
 ///
 /// ## Examples
 ///
@@ -236,8 +236,8 @@ pub fn lazy_or(
 }
 
 /// Combines a list of results into a single result.
-/// If all elements in the list are Ok then returns an Ok holding the list of values.
-/// If any element is Error then returns the first error.
+/// If all elements in the list are `Ok` then returns an `Ok` holding the list of values.
+/// If any element is Error `then` returns the first error.
 ///
 /// ## Examples
 ///    > all([Ok(1), Ok(2)])
@@ -254,8 +254,7 @@ pub fn replace_error(result: Result(a, e1), error: e2) -> Result(a, e2) {
   |> map_error(fn(_) { error })
 }
 
-/// Given a list of results
-/// Return only the values inside Ok
+/// Given a list of results, returns only the values inside `Ok`.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/set.gleam b/src/gleam/set.gleam
index 492ed81..632c951 100644
--- a/src/gleam/set.gleam
+++ b/src/gleam/set.gleam
@@ -77,7 +77,7 @@ pub fn contains(in set: Set(member), this member: member) -> Bool {
   |> result.is_ok
 }
 
-/// Removes an member from a set. If the set does not contain the member then
+/// Removes a member from a set. If the set does not contain the member then
 /// the set is returned unchanged.
 ///
 /// This function runs in logarithmic time.
@@ -149,7 +149,7 @@ pub fn fold(
 }
 
 /// Creates a new set from an existing set, minus any members that a given
-/// function returns False for.
+/// function returns `False` for.
 ///
 /// This function runs in loglinear time.
 ///
diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam
index 60e34e4..dedee4a 100644
--- a/src/gleam/string.gleam
+++ b/src/gleam/string.gleam
@@ -56,7 +56,6 @@ if javascript {
     "../gleam_stdlib.js" "string_length"
 }
 
-///
 /// Reverses a string.
 ///
 /// This function has to iterate across the whole string so it runs in linear
@@ -176,7 +175,7 @@ if javascript {
     "../gleam_stdlib.js" "less_than"
 }
 
-/// Takes a substring given a start and end Grapheme indexes. Negative indexes
+/// Takes a substring given a start and end grapheme indexes. Negative indexes
 /// are taken starting from the *end* of the list.
 ///
 /// ## Examples
@@ -250,7 +249,7 @@ if javascript {
     "../gleam_stdlib.js" "crop_string"
 }
 
-/// Drops *n* Graphemes from the left side of a string.
+/// Drops *n* graphemes from the left side of a string.
 ///
 /// ## Examples
 ///    > drop_left(from: "The Lone Gunmen", up_to: 2)
@@ -263,7 +262,7 @@ pub fn drop_left(from string: String, up_to num_graphemes: Int) -> String {
   }
 }
 
-/// Drops *n* Graphemes from the right side of a string.
+/// Drops *n* graphemes from the right side of a string.
 ///
 /// ## Examples
 ///    > drop_right(from: "Cigarette Smoking Man", up_to: 2)
@@ -412,7 +411,7 @@ if javascript {
 /// Creates a new string by joining two strings together.
 ///
 /// This function copies both strings and runs in linear time. If you find
-/// yourself joining strings frequently consider using the [string_builder](../string_builder)
+/// yourself joining strings frequently consider using the [`string_builder`](../string_builder)
 /// module as it can append strings much faster!
 ///
 /// ## Examples
@@ -430,7 +429,7 @@ pub fn append(to first: String, suffix second: String) -> String {
 /// Creates a new string by joining many strings together.
 ///
 /// This function copies both strings and runs in linear time. If you find
-/// yourself joining strings frequently consider using the [string_builder](../string_builder)
+/// yourself joining strings frequently consider using the [`string_builder`](../string_builder)
 /// module as it can append strings much faster!
 ///
 /// ## Examples
@@ -475,7 +474,7 @@ pub fn join(strings: List(String), with separator: String) -> String {
   |> concat
 }
 
-/// Pads a string on the left until it has at least given number of Graphemes.
+/// Pads a string on the left until it has at least given number of graphemes.
 ///
 /// ## Examples
 ///
@@ -532,7 +531,7 @@ fn padding(size: Int, pad_string: String) -> Iterator(String) {
   |> iterator.append(iterator.single(slice(pad_string, 0, extra)))
 }
 
-/// Removes whitespace on both sides of a String.
+/// Removes whitespace on both sides of a string.
 ///
 /// ## Examples
 ///
@@ -563,7 +562,7 @@ if javascript {
     "../gleam_stdlib.js" "trim"
 }
 
-/// Removes whitespace on the left of a String.
+/// Removes whitespace on the left of a string.
 ///
 /// ## Examples
 ///
@@ -585,7 +584,7 @@ if javascript {
     "../gleam_stdlib.js" "trim_left"
 }
 
-/// Removes whitespace on the right of a String.
+/// Removes whitespace on the right of a string.
 ///
 /// ## Examples
 ///
@@ -631,7 +630,7 @@ if javascript {
     "../gleam_stdlib.js" "pop_grapheme"
 }
 
-/// Converts a string to a list of Graphemes.
+/// Converts a string to a list of graphemes.
 ///
 ///    > to_graphemes("abc")
 ///    ["a", "b", "c"]
@@ -653,7 +652,7 @@ if javascript {
     "../gleam_stdlib.js" "codepoint"
 }
 
-/// Converts an integer to a UtfCodepoint
+/// Converts an integer to a `UtfCodepoint`.
 ///
 /// Returns an error if the integer does not represent a valid UTF codepoint.
 ///
diff --git a/src/gleam/string_builder.gleam b/src/gleam/string_builder.gleam
index 2e6cc2b..f1cc22a 100644
--- a/src/gleam/string_builder.gleam
+++ b/src/gleam/string_builder.gleam
@@ -1,11 +1,11 @@
-/// StringBuilder is a type used for efficiently building strings.
+/// `StringBuilder` is a type used for efficiently building strings.
 ///
 /// When we append one string to another the strings must be copied to a
 /// new location in memory so that they can sit together. This behaviour
 /// enables efficient reading of the string but copying can be expensive,
 /// especially if we want to join many strings together.
 ///
-/// StringBuilder is different in that it can be joined together in constant time
+/// `StringBuilder` is different in that it can be joined together in constant time
 /// using minimal memory, and then can be efficiently converted to a string
 /// using the `to_string` function.
 ///
@@ -14,7 +14,7 @@
 ///
 pub external type StringBuilder
 
-/// Prepends a String onto the start of some StringBuilder.
+/// Prepends a `String` onto the start of some `StringBuilder`.
 ///
 /// Runs in constant time.
 ///
@@ -25,7 +25,7 @@ pub fn prepend(
   append_builder(from_string(prefix), builder)
 }
 
-/// Appends a String onto the end of some StringBuilder.
+/// Appends a `String` onto the end of some `StringBuilder`.
 ///
 /// Runs in constant time.
 ///
@@ -33,7 +33,7 @@ pub fn append(to builder: StringBuilder, suffix second: String) -> StringBuilder
   append_builder(builder, from_string(second))
 }
 
-/// Prepends some StringBuilder onto the start of another.
+/// Prepends some `StringBuilder` onto the start of another.
 ///
 /// Runs in constant time.
 ///
@@ -44,7 +44,7 @@ pub fn prepend_builder(
   do_append(prefix, builder)
 }
 
-/// Appends some StringBuilder onto the end of another.
+/// Appends some `StringBuilder` onto the end of another.
 ///
 /// Runs in constant time.
 ///
@@ -138,7 +138,7 @@ if javascript {
     "../gleam_stdlib.js" "identity"
 }
 
-/// Returns the size of the StringBuilder in bytes.
+/// Returns the size of the `StringBuilder` in bytes.
 ///
 pub fn byte_size(builder: StringBuilder) -> Int {
   do_byte_size(builder)
@@ -282,7 +282,7 @@ if javascript {
 
 /// Compares two builders to determine if they have the same textual content.
 ///
-/// Comparing two iodata using the `==` operator may return False even if they
+/// Comparing two iodata using the `==` operator may return `False` even if they
 /// have the same content as they may have been build in different ways, so
 /// using this function is often preferred.
 ///
diff --git a/src/gleam/uri.gleam b/src/gleam/uri.gleam
index b1d5ed1..3b1c731 100644
--- a/src/gleam/uri.gleam
+++ b/src/gleam/uri.gleam
@@ -366,13 +366,13 @@ pub fn to_string(uri: Uri) -> String {
   string.concat(parts)
 }
 
-/// Fetches the origin of a uri
+/// Fetches the origin of a URI.
 ///
-/// Return the origin of a uri as defined in
+/// Returns the origin of a uri as defined in
 /// https://tools.ietf.org/html/rfc6454
 ///
-/// The supported uri schemes are `http` and `https`
-/// Urls without a scheme will return Error
+/// The supported URI schemes are `http` and `https`.
+/// URLs without a scheme will return `Error`.
 ///
 /// ## Examples
 ///
@@ -410,10 +410,11 @@ fn join_segments(segments: List(String)) -> String {
   string.join(["", ..segments], "/")
 }
 
-/// Resolves a uri with respect to the given base uri
+/// Resolves a URI with respect to the given base URI.
 ///
-/// The base uri must be an absolute uri or this function will return an error.
+/// The base URI must be an absolute URI or this function will return an error.
 /// The algorithm for merging uris is described in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-5.2)
+///
 pub fn merge(base: Uri, relative: Uri) -> Result(Uri, Nil) {
   case base {
     Uri(scheme: Some(_), host: Some(_), ..) ->