Use consistent phrasing in function docs

19 files changed, 199 insertions, 199 deletions

diff --git a/src/gleam/atom.gleam b/src/gleam/atom.gleam
index d53c7ad..e85f5d5 100644
--- a/src/gleam/atom.gleam
+++ b/src/gleam/atom.gleam
@@ -21,7 +21,7 @@ pub type FromStringError {
   AtomNotLoaded
 }
 
-/// Find an existing Atom for the given String.
+/// Finds an existing Atom for the given String.
 ///
 /// If no atom is found in the virtual machine's atom table for the String then
 /// an error is returned.
@@ -37,7 +37,7 @@ pub type FromStringError {
 pub external fn from_string(String) -> Result(Atom, FromStringError) =
   "gleam_stdlib" "atom_from_string"
 
-/// Create an atom from a string, inserting a new value into the virtual
+/// Creates an atom from a string, inserting a new value into the virtual
 /// machine's atom table if an atom does not already exist for the given
 /// string.
 ///
diff --git a/src/gleam/bit_builder.gleam b/src/gleam/bit_builder.gleam
index 12b3448..d69fea5 100644
--- a/src/gleam/bit_builder.gleam
+++ b/src/gleam/bit_builder.gleam
@@ -15,21 +15,21 @@ import gleam/string_builder.{StringBuilder}
 ///
 pub external type BitBuilder
 
-/// Prepend a bit string to the start of a builder.
+/// Prepends a bit string to the start of a builder.
 ///
 /// Runs in constant time.
 ///
 pub external fn prepend(to: BitBuilder, prefix: BitString) -> BitBuilder =
   "gleam_stdlib" "iodata_prepend"
 
-/// Append a bit string to the end of a builder.
+/// Appends a bit string to the end of a builder.
 ///
 /// Runs in constant time.
 ///
 pub external fn append(to: BitBuilder, suffix: BitString) -> BitBuilder =
   "gleam_stdlib" "iodata_append"
 
-/// Prepend a builder onto the start of another.
+/// Prepends a builder onto the start of another.
 ///
 /// Runs in constant time.
 ///
@@ -39,21 +39,21 @@ pub external fn prepend_builder(
 ) -> BitBuilder =
   "gleam_stdlib" "iodata_prepend"
 
-/// Append a builder onto the end of another.
+/// Appends a builder onto the end of another.
 ///
 /// Runs in constant time.
 ///
 pub external fn append_builder(to: BitBuilder, suffix: BitBuilder) -> BitBuilder =
   "gleam_stdlib" "iodata_append"
 
-/// Prepend a string onto the start of a builder.
+/// Prepends a string onto the start of a builder.
 ///
 /// Runs in constant time.
 ///
 pub external fn prepend_string(to: BitBuilder, prefix: String) -> BitBuilder =
   "gleam_stdlib" "iodata_prepend"
 
-/// Append a string onto the end of a builder.
+/// Appends a string onto the end of a builder.
 ///
 /// Runs in constant time.
 ///
@@ -67,21 +67,21 @@ pub external fn append_string(to: BitBuilder, suffix: String) -> BitBuilder =
 pub external fn concat(List(BitBuilder)) -> BitBuilder =
   "gleam_stdlib" "identity"
 
-/// Create a new builder from a string.
+/// Creates a new builder from a string.
 ///
 /// Runs in constant time.
 ///
 pub external fn from_string(String) -> BitBuilder =
   "gleam_stdlib" "wrap_list"
 
-/// Create a new builder from a string builder.
+/// Creates a new builder from a string builder.
 ///
 /// Runs in constant time.
 ///
 pub external fn from_string_builder(StringBuilder) -> BitBuilder =
   "gleam_stdlib" "identity"
 
-/// Create a new builder from a bit string.
+/// Creates a new builder from a bit string.
 ///
 /// Runs in constant time.
 ///
diff --git a/src/gleam/bit_string.gleam b/src/gleam/bit_string.gleam
index d0b91a0..4e10268 100644
--- a/src/gleam/bit_string.gleam
+++ b/src/gleam/bit_string.gleam
@@ -5,7 +5,7 @@
 pub type BitString =
   BitString
 
-/// Convert a UTF-8 String type into a raw BitString type.
+/// Converts a UTF-8 String type into a raw BitString type.
 ///
 pub external fn from_string(String) -> BitString =
   "gleam_stdlib" "identity"
@@ -15,7 +15,7 @@ pub external fn from_string(String) -> BitString =
 pub external fn byte_size(BitString) -> Int =
   "erlang" "byte_size"
 
-/// Create a new bit string by joining two binaries.
+/// Creates a new bit string by joining two binaries.
 ///
 /// ## Examples
 ///
@@ -38,7 +38,7 @@ pub external fn part(
 ) -> Result(BitString, Nil) =
   "gleam_stdlib" "bit_string_part_"
 
-/// Convert an integer to unsigned 32 bits.
+/// Converts an integer to unsigned 32 bits.
 ///
 /// Returns an error if integer is less than zero or equal to or larger than
 /// 2^32.
@@ -46,14 +46,14 @@ pub external fn part(
 pub external fn int_to_u32(Int) -> Result(BitString, Nil) =
   "gleam_stdlib" "bit_string_int_to_u32"
 
-/// Convert unsigned 32 bits to an integer.
+/// Converts unsigned 32 bits to an integer.
 ///
 /// Returns an error if the bit string is not 32 bits in length.
 ///
 pub external fn int_from_u32(BitString) -> Result(Int, Nil) =
   "gleam_stdlib" "bit_string_int_from_u32"
 
-/// Test to see whether a bit string is valid UTF-8.
+/// Tests to see whether a bit string is valid UTF-8.
 ///
 pub fn is_utf8(bits: BitString) -> Bool {
   case bits {
@@ -66,7 +66,7 @@ pub fn is_utf8(bits: BitString) -> Bool {
 external fn unsafe_to_string(BitString) -> String =
   "gleam_stdlib" "identity"
 
-/// Convert a bit string to a string.
+/// Converts a bit string to a string.
 ///
 /// Returns an error if the bit string is invalid UTF-8 data.
 ///
diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam
index 9356083..55462b2 100644
--- a/src/gleam/dynamic.gleam
+++ b/src/gleam/dynamic.gleam
@@ -14,12 +14,12 @@ pub external type Dynamic
 pub type Decoder(t) =
   fn(Dynamic) -> Result(t, String)
 
-/// Convert any Gleam data into `Dynamic` data.
+/// Converts any Gleam data into `Dynamic` data.
 ///
 pub external fn from(a) -> Dynamic =
   "gleam_stdlib" "identity"
 
-/// Unsafely cast a Dynamic value into any other type.
+/// Unsafely casts a Dynamic value into any other type.
 ///
 /// This is an escape hatch for the type system that may be useful when wrapping
 /// native Erlang APIs. It is to be used as a last measure only!
@@ -29,7 +29,7 @@ pub external fn from(a) -> Dynamic =
 pub external fn unsafe_coerce(Dynamic) -> a =
   "gleam_stdlib" "identity"
 
-/// Check 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 return the bit_string if
 /// it is.
 ///
 /// ## Examples
@@ -43,7 +43,7 @@ pub external fn unsafe_coerce(Dynamic) -> a =
 pub external fn bit_string(from: Dynamic) -> Result(BitString, String) =
   "gleam_stdlib" "decode_bit_string"
 
-/// Check 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 return the string if
 /// it is.
 ///
 /// ## Examples
@@ -64,7 +64,7 @@ pub fn string(from: Dynamic) -> Result(String, String) {
   })
 }
 
-/// Check 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 return the int if it
 /// is.
 ///
 /// ## Examples
@@ -78,7 +78,7 @@ pub fn string(from: Dynamic) -> Result(String, String) {
 pub external fn int(from: Dynamic) -> Result(Int, String) =
   "gleam_stdlib" "decode_int"
 
-/// Check to see whether a Dynamic value is an float, and return the float if
+/// Checks to see whether a Dynamic value is an float, and return the float if
 /// it is.
 ///
 /// ## Examples
@@ -92,7 +92,7 @@ pub external fn int(from: Dynamic) -> Result(Int, String) =
 pub external fn float(from: Dynamic) -> Result(Float, String) =
   "gleam_stdlib" "decode_float"
 
-/// Check to see whether a Dynamic value is an atom, and return the atom if
+/// Checks to see whether a Dynamic value is an atom, and return the atom if
 /// it is.
 ///
 /// ## Examples
@@ -107,7 +107,7 @@ pub external fn float(from: Dynamic) -> Result(Float, String) =
 pub external fn atom(from: Dynamic) -> Result(atom.Atom, String) =
   "gleam_stdlib" "decode_atom"
 
-/// Check to see whether a Dynamic value is an bool, and return the bool if
+/// Checks to see whether a Dynamic value is an bool, and return the bool if
 /// it is.
 ///
 /// ## Examples
@@ -121,7 +121,7 @@ pub external fn atom(from: Dynamic) -> Result(atom.Atom, String) =
 pub external fn bool(from: Dynamic) -> Result(Bool, String) =
   "gleam_stdlib" "decode_bool"
 
-/// Check to see whether a Dynamic value is a function that takes no arguments,
+/// Checks to see whether a Dynamic value is a function that takes no arguments,
 /// and return the function if it is.
 ///
 /// ## Examples
@@ -137,7 +137,7 @@ pub external fn bool(from: Dynamic) -> Result(Bool, String) =
 pub external fn thunk(from: Dynamic) -> Result(fn() -> Dynamic, String) =
   "gleam_stdlib" "decode_thunk"
 
-/// Check 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 return the list if it
 /// is.
 ///
 /// If you wish to decode all the elements in the list use the `typed_list`
@@ -154,7 +154,7 @@ pub external fn thunk(from: Dynamic) -> Result(fn() -> Dynamic, String) =
 pub external fn list(from: Dynamic) -> Result(List(Dynamic), String) =
   "gleam_stdlib" "decode_list"
 
-/// Check 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 return the result if
 /// it is
 ///
 /// ## Examples
@@ -188,7 +188,7 @@ pub fn result(from: Dynamic) -> Result(Result(Dynamic, Dynamic), String) {
   }
 }
 
-/// Check to see whether a Dynamic value is a result of a particular type, and
+/// Checks to see whether a Dynamic value is a result of a particular type, and
 /// return the result if it is
 ///
 /// The `ok` and `error` arguments are decoders for decoding the `Ok` and
@@ -224,7 +224,7 @@ pub fn typed_result(
   }
 }
 
-/// Check to see whether a Dynamic value is a list of a particular type, and
+/// Checks to see whether a Dynamic value is a list of a particular type, and
 /// return the list if it is.
 ///
 /// The second argument is a decoder function used to decode the elements of
@@ -254,7 +254,7 @@ pub fn typed_list(
   |> result.then(list.try_map(_, decoder_type))
 }
 
-/// Check to see if a Dynamic value is an Option of a particular type, and return
+/// Checks to see if a Dynamic value is an Option of a particular type, and return
 /// the Option if it is.
 ///
 /// The second argument is a decoder function used to decode the elements of
@@ -284,7 +284,7 @@ pub fn option(
   }
 }
 
-/// Check to see if a Dynamic value is a map with a specific field, and return
+/// Checks to see if a Dynamic value is a map with a specific field, and return
 /// the value of the field if it is.
 ///
 /// This will not succeed on a record.
@@ -301,7 +301,7 @@ pub fn option(
 pub external fn field(from: Dynamic, named: a) -> Result(Dynamic, String) =
   "gleam_stdlib" "decode_field"
 
-/// Check to see if the Dynamic value is a tuple large enough to have a certain
+/// 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.
 ///
 /// ## Examples
@@ -318,7 +318,7 @@ pub external fn field(from: Dynamic, named: a) -> Result(Dynamic, String) =
 pub external fn element(from: Dynamic, position: Int) -> Result(Dynamic, String) =
   "gleam_stdlib" "decode_element"
 
-/// Check to see if the Dynamic value is a 2 element tuple.
+/// Checks to see if the 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.
@@ -337,7 +337,7 @@ pub external fn element(from: Dynamic, position: Int) -> Result(Dynamic, String)
 pub external fn tuple2(from: Dynamic) -> Result(tuple(Dynamic, Dynamic), String) =
   "gleam_stdlib" "decode_tuple2"
 
-/// Check to see if the Dynamic value is a 2 element tuple containing two
+/// Checks to see if the Dynamic value is a 2 element tuple containing two
 /// specifically typed elements.
 ///
 /// If you wish to decode all the elements in the list use the `typed_tuple2`
@@ -368,11 +368,11 @@ pub fn typed_tuple2(
   Ok(tuple(a, b))
 }
 
-/// Check to see if the Dynamic value is map.
+/// Checks to see if the Dynamic value is map.
 ///
 /// ## Examples
 ///
-///    > import gleam/map 
+///    > import gleam/map
 ///    > map(from(map.new()))
 ///    Ok(map.new())
 ///
@@ -385,7 +385,7 @@ pub fn typed_tuple2(
 pub external fn map(from: Dynamic) -> Result(Map(Dynamic, Dynamic), String) =
   "gleam_stdlib" "decode_map"
 
-/// Join multiple decoders into one. When run they will each be tried in turn
+/// Joins multiple decoders into one. When run they will each be tried in turn
 /// until one succeeds, or they all fail.
 ///
 /// ## Examples
diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index a672eca..2a646c2 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -17,7 +17,7 @@ pub type Float =
 pub external fn parse(String) -> Result(Float, Nil) =
   "gleam_stdlib" "parse_float"
 
-/// Return the string representation of the provided float.
+/// Returns the string representation of the provided float.
 ///
 /// ## Examples
 ///    > to_string(2.3)
@@ -29,7 +29,7 @@ pub fn to_string(f: Float) -> String {
   |> string_builder.to_string
 }
 
-/// Restrict a Float between a lower and upper bound
+/// Restricts a Float between a lower and upper bound
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index 96b4405..b77500c 100644
--- a/src/gleam/int.gleam
+++ b/src/gleam/int.gleam
@@ -20,7 +20,7 @@ pub fn absolute_value(num: Int) -> Int {
   }
 }
 
-/// Parse a given string as an int if possible.
+/// Parses a given string as an int if possible.
 ///
 /// ## Examples
 ///
@@ -33,7 +33,7 @@ pub fn absolute_value(num: Int) -> Int {
 pub external fn parse(String) -> Result(Int, Nil) =
   "gleam_stdlib" "parse_int"
 
-/// Print a given int to a string.
+/// Prints a given int to a string.
 ///
 /// ## Examples
 ///
@@ -43,7 +43,7 @@ pub external fn parse(String) -> Result(Int, Nil) =
 pub external fn to_string(Int) -> String =
   "erlang" "integer_to_binary"
 
-/// Print a given int to a string using the base number provided.
+/// Prints a given int to a string using the base number provided.
 ///
 /// ## Examples
 ///
@@ -75,7 +75,7 @@ pub external fn to_base_string(Int, Int) -> String =
 pub external fn to_float(a: Int) -> Float =
   "erlang" "float"
 
-/// Restrict an Int between a lower and upper bound
+/// Restricts an Int between a lower and upper bound
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/io.gleam b/src/gleam/io.gleam
index 88fece6..a5b37df 100644
--- a/src/gleam/io.gleam
+++ b/src/gleam/io.gleam
@@ -29,7 +29,7 @@ pub fn println(string: String) -> Nil {
   Nil
 }
 
-/// Print a value to standard output using Erlang syntax.
+/// Prints a value to standard output using Erlang syntax.
 ///
 /// The value is returned after being printed so it can be used in pipelines.
 ///
@@ -68,7 +68,7 @@ pub type GetLineError {
 /// # Example
 ///
 ///    > io.get_line("Language: ")
-///    // -> Language: <- gleam 
+///    // -> Language: <- gleam
 ///    Ok("gleam\n")
 ///
 pub external fn get_line(prompt: String) -> Result(String, GetLineError) =
diff --git a/src/gleam/iterator.gleam b/src/gleam/iterator.gleam
index 81ef2ce..9bbf9d0 100644
--- a/src/gleam/iterator.gleam
+++ b/src/gleam/iterator.gleam
@@ -40,7 +40,7 @@ fn do_unfold(
   }
 }
 
-/// Create an iterator from a given function and accumulator.
+/// Creates an iterator from a given function and accumulator.
 ///
 /// The function is called on the accumulator and return either `Done`,
 /// indicating the iterator has no more elements, or `Next` which contains a
@@ -69,14 +69,14 @@ pub fn unfold(
 }
 
 // TODO: test
-/// Create an iterator that yields values created by calling a given function
+/// Creates an iterator that yields values created by calling a given function
 /// repeatedly.
 ///
 pub fn repeatedly(f: fn() -> element) -> Iterator(element) {
   unfold(Nil, fn(_) { Next(f(), Nil) })
 }
 
-/// Create an iterator that returns the same value infinitely.
+/// Creates an iterator that returns the same value infinitely.
 ///
 /// ## Examples
 ///
@@ -89,7 +89,7 @@ pub fn repeat(x: element) -> Iterator(element) {
   repeatedly(fn() { x })
 }
 
-/// Create an iterator the yields each element in a given list.
+/// Creates an iterator the yields each element in a given list.
 ///
 /// ## Examples
 ///
@@ -118,7 +118,7 @@ fn do_fold(
   }
 }
 
-/// Reduce an iterator of elements into a single value by calling a given
+/// Reduces an iterator of elements into a single value by calling a given
 /// function on each element in turn.
 ///
 /// If called on an iterator of infinite length then this function will never
@@ -144,7 +144,7 @@ pub fn fold(
 }
 
 // TODO: test
-/// Evaluate all elements in a given stream. This function is useful for when
+/// Evaluates all elements in a given stream. This function is useful for when
 /// you wish to trigger any side effects that would occur when evaluating
 /// the iterator.
 ///
@@ -152,7 +152,7 @@ pub fn run(iterator: Iterator(e)) -> Nil {
   fold(iterator, Nil, fn(_, _) { Nil })
 }
 
-/// Evaluate an iterator and return all the elements as a list.
+/// Evaluates an iterator and return all the elements as a list.
 ///
 /// If called on an iterator of infinite length then this function will never
 /// return.
@@ -168,7 +168,7 @@ pub fn to_list(iterator: Iterator(element)) -> List(element) {
   |> list.reverse
 }
 
-/// Eagerly access the first value of an interator, returning a `Next`
+/// Eagerly accesses the first value of an interator, returning a `Next`
 /// that contains the first value and the rest of the iterator.
 ///
 /// If called on an empty iterator, `Done` is returned.
@@ -216,7 +216,7 @@ fn do_take(
   }
 }
 
-/// Evaluate a desired number of elements from an iterator and return them in a
+/// Evaluates a desired number of elements from an iterator and return them in a
 /// list.
 ///
 /// If the iterator does not have enough elements all of them are returned.
@@ -245,7 +245,7 @@ fn do_drop(continuation: fn() -> Action(e), desired: Int) -> fn() -> Action(e) {
   }
 }
 
-/// Evaluate and discard the first N elements in an iterator, returning a new
+/// Evaluates and discards the first N elements in an iterator, returning a new
 /// iterator.
 ///
 /// If the iterator does not have enough elements an empty iterator is
@@ -277,7 +277,7 @@ fn do_map(continuation: fn() -> Action(a), f: fn(a) -> b) -> fn() -> Action(b) {
   }
 }
 
-/// Create an iterator from an existing iterator and a transformation function.
+/// Creates an iterator from an existing iterator and a transformation function.
 ///
 /// Each element in the new iterator will be the result of calling the given
 /// function on the elements in the given iterator.
@@ -308,7 +308,7 @@ fn do_append(
   }
 }
 
-/// Append two iterators, producing a new iterator.
+/// Appends two iterators, producing a new iterator.
 ///
 /// This function does not evaluate the elements of the iterators, the
 /// computation is performed when the resulting iterator is later run.
@@ -334,7 +334,7 @@ fn do_flatten(continuation: fn() -> Action(Iterator(a))) -> fn() -> Action(a) {
   }
 }
 
-/// Flatten an iterator of iterator of iterators, creating a new iterator.
+/// Flattens an iterator of iterator of iterators, creating a new iterator.
 ///
 /// This function does not evaluate the elements of the iterator, the
 /// computation is performed when the iterator is later run.
@@ -350,7 +350,7 @@ pub fn flatten(iterator: Iterator(Iterator(a))) -> Iterator(a) {
   |> Iterator
 }
 
-/// Create an iterator from an existing iterator and a transformation function.
+/// Creates an iterator from an existing iterator and a transformation function.
 ///
 /// Each element in the new iterator will be the result of calling the given
 /// function on the elements in the given iterator and then flattening the
@@ -389,7 +389,7 @@ fn do_filter(
   }
 }
 
-/// Create an iterator from an existing iterator and a predicate function.
+/// Creates an iterator from an existing iterator and a predicate function.
 ///
 /// The new iterator will contain elements from the first iterator for which
 /// the given function returns `True`.
@@ -421,7 +421,7 @@ fn do_cycle(next: fn() -> Action(a), reset: fn() -> Action(a)) {
   }
 }
 
-/// Create an iterator that repeats a given iterator infinitely.
+/// Creates an iterator that repeats a given iterator infinitely.
 ///
 /// ## Examples
 ///
@@ -441,7 +441,7 @@ fn do_range(current, limit, inc) -> fn() -> Action(Int) {
   }
 }
 
-/// Create an iterator of ints, starting at a given start int and stepping by
+/// Creates an iterator of ints, starting at a given start int and stepping by
 /// one to a given end int.
 ///
 /// ## Examples
@@ -464,7 +464,7 @@ pub fn range(from start: Int, to stop: Int) -> Iterator(Int) {
   |> Iterator
 }
 
-/// Find the first element in a given iterator for which the given function returns
+/// Finds the first element in a given iterator for which the given function returns
 /// True.
 ///
 /// Returns `Error(Nil)` if the function does not return True for any of the
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index b6afb3c..f69e82c 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -31,7 +31,7 @@ pub type LengthMismatch {
   LengthMismatch
 }
 
-/// Count the number of elements in a given list.
+/// Counts the number of elements in a given list.
 ///
 /// This function has to traverse the list to determine the number of elements,
 /// so it runs in linear time.
@@ -53,7 +53,7 @@ pub type LengthMismatch {
 pub external fn length(of: List(a)) -> Int =
   "erlang" "length"
 
-/// Create a new list from a given list containing the same elements but in the
+/// Creates a new list from a given list containing the same elements but in the
 /// opposite order.
 ///
 /// This function has to traverse the list to create the new reversed list, so
@@ -76,7 +76,7 @@ pub external fn length(of: List(a)) -> Int =
 pub external fn reverse(List(a)) -> List(a) =
   "lists" "reverse"
 
-/// Determine whether or not the list is empty.
+/// Determines whether or not the list is empty.
 ///
 /// This function runs in constant time.
 ///
@@ -95,7 +95,7 @@ pub fn is_empty(list: List(a)) -> Bool {
   list == []
 }
 
-/// Determine whether or not a given element exists within a given list.
+/// Determines whether or not a given element exists within a given list.
 ///
 /// This function traverses the list to find the element, so it runs in linear
 /// time.
@@ -124,7 +124,7 @@ pub fn contains(list: List(a), any elem: a) -> Bool {
   }
 }
 
-/// Get the first element from the start of the list, if there is one.
+/// Gets the first element from the start of the list, if there is one.
 ///
 /// ## Examples
 ///
@@ -144,7 +144,7 @@ pub fn head(list: List(a)) -> Result(a, Nil) {
   }
 }
 
-/// Get the list minus the first element. If the list is empty `Error(Nil)` is
+/// Gets 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.
@@ -388,7 +388,7 @@ pub fn new() -> List(a) {
   []
 }
 
-/// Join one list onto the end of another.
+/// Joins one list onto the end of another.
 ///
 /// This function runs in linear time, and it traverses and copies the first
 /// list.
@@ -422,7 +422,7 @@ 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
+/// Reduces 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)))`.
@@ -436,7 +436,7 @@ pub fn fold(over 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
+/// Reduces 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
@@ -555,7 +555,7 @@ pub fn fold_until(
   }
 }
 
-/// Find the first element in a given list for which the given function returns
+/// Finds 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
@@ -586,7 +586,7 @@ pub fn find(
   }
 }
 
-/// Find the first element in a given list for which the given function returns
+/// 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.
 ///
 /// Returns `Error(Nil)` if no the function does not return Ok for any of the
@@ -748,7 +748,7 @@ pub fn unzip(input: List(tuple(a, b))) -> tuple(List(a), List(b)) {
   do_unzip(input, [], [])
 }
 
-/// Insert a given value between each existing element in a given list.
+/// Inserts a given value between each existing element in a given list.
 ///
 /// This function runs in linear time and copies the list.
 ///
@@ -767,7 +767,7 @@ 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
+/// 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.
@@ -795,7 +795,7 @@ pub fn at(in list: List(a), get index: Int) -> Result(a, Nil) {
   }
 }
 
-/// Remove any duplicate elements from a given list.
+/// Removes any duplicate elements from a given list.
 ///
 /// This function returns in log-linear time (n log n).
 ///
@@ -843,7 +843,7 @@ fn do_sort(
   }
 }
 
-/// Sort from smallest to largest based upon the ordering specified by a given
+/// Sorts from smallest to largest based upon the ordering specified by a given
 /// function.
 ///
 /// ## Examples
@@ -856,7 +856,7 @@ pub fn sort(list: List(a), 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.
+/// Creates a list of ints ranging from a given start and finish.
 ///
 /// ## Examples
 ///
@@ -884,7 +884,7 @@ fn do_repeat(a: a, times: Int, acc: List(a)) -> List(a) {
   }
 }
 
-/// Build a list of a given value a given number of times.
+/// Builds a list of a given value a given number of times.
 ///
 /// ## Examples
 ///
@@ -909,7 +909,7 @@ fn do_split(list: List(a), n: Int, taken: List(a)) -> tuple(List(a), List(a)) {
   }
 }
 
-/// Split a list in two before the given index.
+/// Splits a list in two before the given index.
 ///
 /// If the list is not long enough to have the given index the before list will
 /// be the input list, and the after list will be empty.
@@ -944,7 +944,7 @@ fn do_split_while(
   }
 }
 
-/// Split a list in two before the first element that a given function returns
+/// Splits a list in two before the first element that a given function returns
 /// False for.
 ///
 /// If the function returns True for all elements the first list will be the
@@ -965,8 +965,8 @@ pub fn split_while(
   do_split_while(list, predicate, [])
 }
 
-/// Given a list of 2 element tuples, find the first tuple that has a given
-/// key as the first element and return the second element.
+/// Given a list of 2 element tuples, finds the first tuple that has a given
+/// key as the first element and returns the second element.
 ///
 /// If no tuple is found with the given key then `Error(Nil)` is returned.
 ///
@@ -1011,7 +1011,7 @@ fn do_pop(haystack, predicate, checked) {
   }
 }
 
-/// Remove the first element in a given list for which the predicate funtion returns `True`.
+/// 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.
@@ -1069,7 +1069,7 @@ pub fn pop_map(
   do_pop_map(haystack, is_desired, [])
 }
 
-/// Given a list of 2 element tuples, find the first tuple that has a given
+/// Given a list of 2 element tuples, finds the first tuple that has a given
 /// key as the first element. This function will return the second element
 /// of the found tuple and list with tuple removed.
 ///
@@ -1102,7 +1102,7 @@ pub fn key_pop(
   )
 }
 
-/// Given a list of 2 element tuples, insert a key and value into the list.
+/// Given a list of 2 element tuples, inserts a key and value into the list.
 ///
 /// If there was already a tuple with the key then it is replaced, otherwise it
 /// is added to the end of the list.
@@ -1124,7 +1124,7 @@ pub fn key_set(list: List(tuple(a, b)), key: a, value: b) -> List(tuple(a, b)) {
   }
 }
 
-/// Call a function for each element in a list, discarding the results.
+/// Calls a function for each element in a list, discarding the results.
 ///
 pub fn each(list: List(a), f: fn(a) -> b) -> Nil {
   case list {
@@ -1154,7 +1154,7 @@ pub fn partition(
   do_partition(list, categorise, [], [])
 }
 
-/// Return all the permutations of a list
+/// Returns all the permutations of a list
 /// All values must be unique
 ///
 /// ## Examples
@@ -1187,7 +1187,7 @@ fn do_window(acc: List(List(a)), l: List(a), n: Int) -> List(List(a)) {
   }
 }
 
-/// Return a list of sliding window
+/// Returns a list of sliding window
 ///
 /// ## Examples
 ///
@@ -1204,7 +1204,7 @@ pub fn window(l: List(a), by n: Int) -> List(List(a)) {
   |> reverse
 }
 
-/// Return a list of tuples containing two contiguous elements
+/// Returns a list of tuples containing two contiguous elements
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/map.gleam b/src/gleam/map.gleam
index 488a315..15b936a 100644
--- a/src/gleam/map.gleam
+++ b/src/gleam/map.gleam
@@ -17,7 +17,7 @@ import gleam/list
 ///
 pub external type Map(key, value)
 
-/// Determine the number of key-value pairs in the map.
+/// Determines the number of key-value pairs in the map.
 /// This function runs in constant time and does not need to iterate the map.
 ///
 /// ## Examples
@@ -32,7 +32,7 @@ pub external type Map(key, value)
 pub external fn size(Map(k, v)) -> Int =
   "maps" "size"
 
-/// Convert the map to a list of 2-element tuples `tuple(key, value)`, one for
+/// Converts the map to a list of 2-element tuples `tuple(key, value)`, one for
 /// each key-value pair in the map.
 ///
 /// The tuples in the list have no specific order.
@@ -48,7 +48,7 @@ pub external fn size(Map(k, v)) -> Int =
 pub external fn to_list(Map(key, value)) -> List(tuple(key, value)) =
   "maps" "to_list"
 
-/// Convert a list of 2-element tuples `tuple(key, value)` to a map.
+/// Converts a list of 2-element tuples `tuple(key, value)` to a map.
 ///
 /// If two tuples have the same key the last one in the list will be the one
 /// that is present in the map.
@@ -59,7 +59,7 @@ pub external fn from_list(List(tuple(key, value))) -> Map(key, value) =
 external fn is_key(key, Map(key, v)) -> Bool =
   "maps" "is_key"
 
-/// Determind whether or not a value present in the map for a given key.
+/// Determines whether or not a value present in the map for a given key.
 ///
 /// ## Examples
 ///
@@ -73,12 +73,12 @@ pub fn has_key(map: Map(k, v), key: k) -> Bool {
   is_key(key, map)
 }
 
-/// Create a fresh map that contains no values.
+/// Creates a fresh map that contains no values.
 ///
 pub external fn new() -> Map(key, value) =
   "maps" "new"
 
-/// Fetch a value from a map for a given key.
+/// 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.
@@ -97,7 +97,7 @@ pub external fn get(from: Map(key, value), get: key) -> Result(value, Nil) =
 external fn erl_insert(key, value, Map(key, value)) -> Map(key, value) =
   "maps" "put"
 
-/// Insert a value into the map with the given key.
+/// Inserts a value into the map with the given key.
 ///
 /// If the map already has a value for the given key then the value is
 /// replaced with the new value.
@@ -117,7 +117,7 @@ pub fn insert(into map: Map(k, v), for key: k, insert value: v) -> Map(k, v) {
 external fn erl_map_values(fn(key, a) -> b, Map(key, value)) -> Map(key, b) =
   "maps" "map"
 
-/// Update all values in a given map by calling a given function on each key
+/// Updates all values in a given map by calling a given function on each key
 /// and value.
 ///
 /// ## Examples
@@ -132,7 +132,7 @@ pub fn map_values(in map: Map(k, v), with fun: fn(k, v) -> w) -> Map(k, w) {
   erl_map_values(fun, map)
 }
 
-/// Get a list of all keys in a given map.
+/// Gets a list of all keys in a given map.
 ///
 /// Maps are not ordered so the keys are not returned in any specific order. Do
 /// not write code that relies on the order keys are returned by this function
@@ -146,7 +146,7 @@ pub fn map_values(in map: Map(k, v), with fun: fn(k, v) -> w) -> Map(k, w) {
 pub external fn keys(Map(keys, v)) -> List(keys) =
   "maps" "keys"
 
-/// Get a list of all values in a given map.
+/// Gets a list of all values in a given map.
 ///
 /// Maps are not ordered so the values are not returned in any specific order. Do
 /// not write code that relies on the order values are returned by this function
@@ -166,7 +166,7 @@ external fn erl_filter(
 ) -> Map(key, value) =
   "maps" "filter"
 
-/// Create a new map from a given map, minus any entries that a given function
+/// Creates a new map from a given map, minus any entries that a given function
 /// returns False for.
 ///
 /// ## Examples
@@ -186,7 +186,7 @@ pub fn filter(in map: Map(k, v), for property: fn(k, v) -> Bool) -> Map(k, v) {
 external fn erl_take(List(k), Map(k, v)) -> Map(k, v) =
   "maps" "with"
 
-/// Create a new map from a given map, only including any entries for which the
+/// Creates a new map from a given map, only including any entries for which the
 /// keys are in a given list.
 ///
 /// ## Examples
@@ -203,7 +203,7 @@ pub fn take(from map: Map(k, v), keeping desired_keys: List(k)) -> Map(k, v) {
   erl_take(desired_keys, map)
 }
 
-/// Create a new map from a pair of given maps by combining their entries.
+/// Creates a new map from a pair of given maps by combining their entries.
 ///
 /// If there are entries with the same keys in both maps the entry from the
 /// second map takes precedence.
@@ -221,7 +221,7 @@ pub external fn merge(into: Map(k, v), merge: Map(k, v)) -> Map(k, v) =
 external fn erl_delete(k, Map(k, v)) -> Map(k, v) =
   "maps" "remove"
 
-/// Create a new map from a given map with all the same entries except for the
+/// Creates a new map from a given map with all the same entries except for the
 /// one with a given key, if it exists.
 ///
 /// ## Examples
@@ -236,7 +236,7 @@ pub fn delete(from map: Map(k, v), delete key: k) -> Map(k, v) {
   erl_delete(key, map)
 }
 
-/// Create a new map from a given map with all the same entries except any with
+/// Creates a new map from a given map with all the same entries except any with
 /// keys found in a given list.
 ///
 /// ## Examples
@@ -254,7 +254,7 @@ pub fn drop(from map: Map(k, v), drop disallowed_keys: List(k)) -> Map(k, v) {
   list.fold(disallowed_keys, map, fn(key, acc) { delete(acc, key) })
 }
 
-/// Create a new map with one entry updated using a given function.
+/// Creates a new map with one entry updated using a given function.
 ///
 /// If there was not an entry in the map for the given key then the function
 /// gets `Error(Nil)` as its argument, otherwise it gets `Ok(value)`.
@@ -297,7 +297,7 @@ fn do_fold(
   }
 }
 
-/// Combine all entries into a single value by calling a given function on each
+/// Combines all entries into a single value by calling a given function on each
 /// one.
 ///
 /// Maps are not ordered so the values are not returned in any specific order. Do
diff --git a/src/gleam/option.gleam b/src/gleam/option.gleam
index c44221b..f597563 100644
--- a/src/gleam/option.gleam
+++ b/src/gleam/option.gleam
@@ -9,7 +9,7 @@ pub type Option(a) {
   None
 }
 
-/// Check whether the option is a Some value.
+/// Checks whether the option is a Some value.
 ///
 /// ## Examples
 ///
@@ -23,7 +23,7 @@ pub fn is_some(option: Option(a)) -> Bool {
   option != None
 }
 
-/// Check whether the option is a None value.
+/// Checks whether the option is a None value.
 ///
 /// ## Examples
 ///
@@ -69,7 +69,7 @@ pub fn from_result(result: Result(a, e)) -> Option(a) {
   }
 }
 
-/// Extract the value from an option, returning a default value if there is none.
+/// Extracts the value from an option, returning a default value if there is none.
 ///
 /// ## Examples
 ///
@@ -86,7 +86,7 @@ pub fn unwrap(option: Option(a), or default: a) -> a {
   }
 }
 
-/// Update 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
@@ -107,7 +107,7 @@ pub fn map(over option: Option(a), with fun: fn(a) -> b) -> Option(b) {
   }
 }
 
-/// Merge a nested Option into a single layer.
+/// Merges a nested Option into a single layer.
 ///
 /// ## Examples
 ///
@@ -127,7 +127,7 @@ pub fn flatten(option: Option(Option(a))) -> Option(a) {
   }
 }
 
-/// Update 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, where the given function also returns an Option. The two Options are
 /// then merged together into one Option.
 ///
@@ -158,7 +158,7 @@ pub fn then(option: Option(a), apply fun: fn(a) -> Option(b)) -> Option(b) {
   }
 }
 
-/// Return the first value if it is Some, otherwise return the second value.
+/// Returns the first value if it is Some, otherwise return the second value.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/os.gleam b/src/gleam/os.gleam
index 0623dd5..6dabe74 100644
--- a/src/gleam/os.gleam
+++ b/src/gleam/os.gleam
@@ -22,7 +22,7 @@ external fn char_list_to_string(CharList) -> String =
 external fn string_to_char_list(String) -> CharList =
   "erlang" "binary_to_list"
 
-/// Return all environment variables set on the system.
+/// Returns all environment variables set on the system.
 pub fn get_env() -> Map(String, String) {
   list.map(
     os_getenv(),
@@ -34,13 +34,13 @@ pub fn get_env() -> Map(String, String) {
   |> map.from_list()
 }
 
-/// Set an environment variable.
+/// Sets an environment variable.
 pub fn insert_env(key: String, value: String) -> Nil {
   os_putenv(string_to_char_list(key), string_to_char_list(value))
   Nil
 }
 
-/// Delete an environment variable.
+/// Deletes an environment variable.
 pub fn delete_env(key: String) -> Nil {
   os_unsetenv(string_to_char_list(key))
   Nil
@@ -53,13 +53,13 @@ pub type TimeUnit {
   Nanosecond
 }
 
-/// Return the current OS system time.
+/// Returns the current OS system time.
 ///
 /// https://erlang.org/doc/apps/erts/time_correction.html#OS_System_Time
 pub external fn system_time(TimeUnit) -> Int =
   "os" "system_time"
 
-/// Return the current OS system time as a tuple of Ints
+/// Returns the current OS system time as a tuple of Ints
 ///
 /// http://erlang.org/doc/man/os.html#timestamp-0
 pub external fn erlang_timestamp() -> tuple(Int, Int, Int) =
diff --git a/src/gleam/queue.gleam b/src/gleam/queue.gleam
index 21fcfa1..09791df 100644
--- a/src/gleam/queue.gleam
+++ b/src/gleam/queue.gleam
@@ -17,13 +17,13 @@ pub opaque type Queue(element) {
   Queue(in: List(element), out: List(element))
 }
 
-/// Create a fresh queue that contains no values.
+/// Creates a fresh queue that contains no values.
 ///
 pub fn new() -> Queue(a) {
   Queue(in: [], out: [])
 }
 
-/// Convert a list of elements into a queue of the same elements in the same
+/// Converts a list of elements into a queue of the same elements in the same
 /// order. The head element in the list becomes the front element in the queue.
 ///
 /// This function runs in constant time.
@@ -37,7 +37,7 @@ pub fn from_list(list: List(a)) -> Queue(a) {
   Queue(in: [], out: list)
 }
 
-/// Convert a queue of elements into a list of the same elements in the same
+/// Converts a queue of elements into a list of the same elements in the same
 /// order. The front element in the queue becomes the head element in the list.
 ///
 /// This function runs in linear time.
@@ -52,7 +52,7 @@ pub fn to_list(queue: Queue(a)) -> List(a) {
   |> list.append(list.reverse(queue.in))
 }
 
-/// Determine whether or not the queue is empty.
+/// Determines whether or not the queue is empty.
 ///
 /// This function runs in constant time.
 ///
@@ -71,7 +71,7 @@ pub fn is_empty(queue: Queue(a)) -> Bool {
   queue.in == [] && queue.out == []
 }
 
-/// Count the number of elements in a given queue.
+/// Counts the number of elements in a given queue.
 ///
 /// This function has to traverse the queue to determine the number of elements,
 /// so it runs in linear time.
@@ -91,7 +91,7 @@ pub fn length(queue: Queue(a)) -> Int {
   list.length(queue.in) + list.length(queue.out)
 }
 
-/// Push an element onto the back of the queue.
+/// Pushes an element onto the back of the queue.
 ///
 /// # Examples
 ///
@@ -102,7 +102,7 @@ pub fn push_back(onto queue: Queue(a), this item: a) -> Queue(a) {
   Queue(in: [item, ..queue.in], out: queue.out)
 }
 
-/// Push an element onto the front of the queue.
+/// Pushes an element onto the front of the queue.
 ///
 /// # Examples
 ///
@@ -113,7 +113,7 @@ pub fn push_front(onto queue: Queue(a), this item: a) -> Queue(a) {
   Queue(in: queue.in, out: [item, ..queue.out])
 }
 
-/// Get the last element from the queue, returning the
+/// Gets the last element from the queue, returning the
 /// element and a new queue without that element.
 ///
 /// This function typically runs in constant time, but will occasionally run in
@@ -147,7 +147,7 @@ pub fn pop_back(from queue: Queue(a)) -> Result(tuple(a, Queue(a)), Nil) {
   }
 }
 
-/// Get the first element from the queue, returning the
+/// Gets the first element from the queue, returning the
 /// element and a new queue without that element.
 ///
 /// This function typically runs in constant time, but will occasionally run in
@@ -181,7 +181,7 @@ pub fn pop_front(from queue: Queue(a)) -> Result(tuple(a, Queue(a)), Nil) {
   }
 }
 
-/// Create a new queue from a given queue containing the same elements, but in
+/// Creates a new queue from a given queue containing the same elements, but in
 /// the opposite order.
 ///
 /// This function runs in constant time.
@@ -221,7 +221,7 @@ fn check_equal(
   }
 }
 
-/// Check whether two queues have equal elements in the same order, where the
+/// Checks whether two queues have equal elements in the same order, where the
 /// equality of elements is determined by a given equality checking function.
 ///
 /// This function is useful as the internal representation may be different for
@@ -240,7 +240,7 @@ pub fn is_logically_equal(
   check_equal(a.out, a.in, b.out, b.in, element_is_equal)
 }
 
-/// Check whether two queues have the same elements in the same order.
+/// Checks whether two queues have the same elements in the same order.
 ///
 /// This function is useful as the internal representation may be different for
 /// two queues with the same elements in the same order depending on how they
diff --git a/src/gleam/regex.gleam b/src/gleam/regex.gleam
index 4317cd5..07aa1ba 100644
--- a/src/gleam/regex.gleam
+++ b/src/gleam/regex.gleam
@@ -35,7 +35,7 @@ pub type Options {
   Options(case_insensitive: Bool, multi_line: Bool)
 }
 
-/// Create a Regex with some additional options.
+/// Creates a Regex with some additional options.
 ///
 /// ## Examples
 ///
@@ -52,7 +52,7 @@ pub type Options {
 pub external fn compile(String, with: Options) -> Result(Regex, CompileError) =
   "gleam_stdlib" "compile_regex"
 
-/// Create a new Regex.
+/// Creates a new Regex.
 ///
 /// ## Examples
 ///
@@ -89,7 +89,7 @@ pub fn from_string(pattern: String) -> Result(Regex, CompileError) {
 pub external fn check(with: Regex, content: String) -> Bool =
   "gleam_stdlib" "regex_match"
 
-/// Split a string
+/// Splits a string
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index efee97a..b9815a5 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -14,7 +14,7 @@ pub type Result(success, error) =
 pub type Nil =
   Nil
 
-/// Check whether the result is an Ok value.
+/// Checks whether the result is an Ok value.
 ///
 /// ## Examples
 ///
@@ -31,7 +31,7 @@ pub fn is_ok(result: Result(a, e)) -> Bool {
   }
 }
 
-/// Check whether the result is an Error value.
+/// Checks whether the result is an Error value.
 ///
 /// ## Examples
 ///
@@ -48,7 +48,7 @@ pub fn is_error(result: Result(a, e)) -> Bool {
   }
 }
 
-/// Update 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
@@ -69,7 +69,7 @@ pub fn map(over result: Result(a, e), with fun: fn(a) -> b) -> Result(b, e) {
   }
 }
 
-/// Update 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
@@ -93,7 +93,7 @@ pub fn map_error(
   }
 }
 
-/// Merge a nested Result into a single layer.
+/// Merges a nested Result into a single layer.
 ///
 /// ## Examples
 ///
@@ -113,7 +113,7 @@ pub fn flatten(result: Result(Result(a, e), e)) -> Result(a, e) {
   }
 }
 
-/// Update 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.
 ///
@@ -147,7 +147,7 @@ pub fn then(
   }
 }
 
-/// Extract the Ok value from a result, returning a default value if the result
+/// Extracts the Ok value from a result, returning a default value if the result
 /// is an Error.
 ///
 /// ## Examples
@@ -165,7 +165,7 @@ pub fn unwrap(result: Result(a, e), or default: a) -> a {
   }
 }
 
-/// Extract the Ok value from a result, evaluating the default function if the result
+/// Extracts the Ok value from a result, evaluating the default function if the result
 /// is an Error.
 ///
 /// ## Examples
@@ -197,7 +197,7 @@ pub fn nil_error(result: Result(a, e)) -> Result(a, Nil) {
   map_error(result, fn(_) { Nil })
 }
 
-/// Return the first value if it is Ok, otherwise return the second value.
+/// Returns the first value if it is Ok, otherwise return the second value.
 ///
 /// ## Examples
 ///
@@ -220,7 +220,7 @@ pub fn or(first: Result(a, e), second: Result(a, e)) -> Result(a, e) {
   }
 }
 
-/// Return 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
 ///
@@ -246,7 +246,7 @@ pub fn lazy_or(
   }
 }
 
-/// Combine a list of results into a single result.
+/// 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.
 ///
diff --git a/src/gleam/set.gleam b/src/gleam/set.gleam
index 0455081..7d9a91e 100644
--- a/src/gleam/set.gleam
+++ b/src/gleam/set.gleam
@@ -13,13 +13,13 @@ pub opaque type Set(member) {
   Set(map: Map(member, List(Nil)))
 }
 
-/// Create a new empty set.
+/// Creates a new empty set.
 ///
 pub fn new() -> Set(member) {
   Set(map.new())
 }
 
-/// Get the number of members in a set.
+/// Gets the number of members in a set.
 ///
 /// This function runs in constant time.
 ///
@@ -32,7 +32,7 @@ pub fn size(set: Set(member)) -> Int {
   map.size(set.map)
 }
 
-/// Insert an member into the set.
+/// Inserts an member into the set.
 ///
 /// This function runs in logarithmic time.
 ///
@@ -45,7 +45,7 @@ pub fn insert(into set: Set(member), this member: member) -> Set(member) {
   Set(map: map.insert(set.map, member, []))
 }
 
-/// Check whether a set contains a given member.
+/// Checks whether a set contains a given member.
 ///
 /// This function runs in logarithmic time.
 ///
@@ -63,7 +63,7 @@ pub fn contains(in set: Set(member), this member: member) -> Bool {
   |> result.is_ok
 }
 
-/// Remove an member from a set. If the set does not contain the member then
+/// Removes an member from a set. If the set does not contain the member then
 /// the set is returned unchanged.
 ///
 /// This function runs in logarithmic time.
@@ -77,7 +77,7 @@ pub fn delete(from set: Set(member), this member: member) -> Set(member) {
   Set(map: map.delete(set.map, member))
 }
 
-/// Convert the set into a list of the contained members.
+/// Converts the set into a list of the contained members.
 ///
 /// The list has no specific ordering, any unintentional ordering may change in
 /// future versions of Gleam or Erlang.
@@ -93,7 +93,7 @@ pub fn to_list(set: Set(member)) -> List(member) {
   map.keys(set.map)
 }
 
-/// Create a new set of the members in a given list.
+/// Creates a new set of the members in a given list.
 ///
 /// This function runs in loglinear time.
 ///
@@ -113,7 +113,7 @@ pub fn from_list(members: List(member)) -> Set(member) {
   Set(map)
 }
 
-/// Combine all entries into a single value by calling a given function on each
+/// Combines all entries into a single value by calling a given function on each
 /// one.
 ///
 /// Sets are not ordered so the values are not returned in any specific order.
@@ -134,7 +134,7 @@ pub fn fold(
   map.fold(over: set.map, from: initial, with: fn(k, _, a) { reducer(k, a) })
 }
 
-/// Create a new set from an existing set, minus any members that a given
+/// Creates a new set from an existing set, minus any members that a given
 /// function returns False for.
 ///
 /// This function runs in loglinear time.
@@ -154,7 +154,7 @@ pub fn filter(
   Set(map.filter(in: set.map, for: fn(m, _) { property(m) }))
 }
 
-/// Create a new map from a given map, only including any members which are in
+/// Creates a new map from a given map, only including any members which are in
 /// a given list.
 ///
 /// This function runs in loglinear time.
@@ -178,7 +178,7 @@ fn order(
   }
 }
 
-/// Create a new set that contains all members of both given sets.
+/// Creates a new set that contains all members of both given sets.
 ///
 /// This function runs in loglinear time.
 ///
@@ -192,7 +192,7 @@ pub fn union(of first: Set(member), and second: Set(member)) -> Set(member) {
   fold(over: smaller, from: larger, with: fn(m, a) { insert(a, m) })
 }
 
-/// Create a new set that contains members that are present in both given sets.
+/// Creates a new set that contains members that are present in both given sets.
 ///
 /// This function runs in loglinear time.
 ///
diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam
index 379bc57..4256dd4 100644
--- a/src/gleam/string.gleam
+++ b/src/gleam/string.gleam
@@ -15,7 +15,7 @@ pub type String =
 pub type UtfCodepoint =
   UtfCodepoint
 
-/// Determine if a string is empty.
+/// Determines if a string is empty.
 ///
 /// ## Examples
 ///
@@ -29,7 +29,7 @@ pub fn is_empty(str: String) -> Bool {
   str == ""
 }
 
-/// Get the number of grapheme clusters in a given string.
+/// Gets the number of grapheme clusters in a given string.
 ///
 /// This function has to iterate across the whole string to count the number of
 /// graphemes, so it runs in linear time.
@@ -49,7 +49,7 @@ pub external fn length(String) -> Int =
   "string" "length"
 
 ///
-/// Reverse a string.
+/// Reverses a string.
 ///
 /// This function has to iterate across the whole string so it runs in linear
 /// time.
@@ -66,7 +66,7 @@ pub fn reverse(string: String) -> String {
   |> string_builder.to_string
 }
 
-/// Create a new string by replacing all occurrences of a given substring.
+/// Creates a new string by replacing all occurrences of a given substring.
 ///
 /// ## Examples
 ///
@@ -87,7 +87,7 @@ pub fn replace(
   |> string_builder.to_string
 }
 
-/// Create a new string with all the graphemes in the input string converted to
+/// Creates a new string with all the graphemes in the input string converted to
 /// lowercase.
 ///
 /// Useful for case-insensitive comparisons.
@@ -100,7 +100,7 @@ pub fn replace(
 pub external fn lowercase(String) -> String =
   "string" "lowercase"
 
-/// Create a new string with all the graphemes in the input string converted to
+/// Creates a new string with all the graphemes in the input string converted to
 /// uppercase.
 ///
 /// Useful for case-insensitive comparisons and VIRTUAL YELLING.
@@ -131,7 +131,7 @@ pub external fn compare(String, String) -> order.Order =
 external fn erl_slice(String, Int, Int) -> String =
   "string" "slice"
 
-/// Take 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
@@ -167,7 +167,7 @@ pub fn slice(from string: String, at_index idx: Int, length len: Int) -> String
   }
 }
 
-/// Drop *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)
@@ -180,7 +180,7 @@ pub fn drop_left(from string: String, up_to num_graphemes: Int) -> String {
   }
 }
 
-/// Drop *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)
@@ -196,7 +196,7 @@ pub fn drop_right(from string: String, up_to num_graphemes: Int) -> String {
 external fn erl_contains(String, String) -> Dynamic =
   "string" "find"
 
-/// Check if the first string contains the second.
+/// Checks if the first string contains the second.
 ///
 /// ## Examples
 ///
@@ -216,7 +216,7 @@ pub fn contains(does haystack: String, contain needle: String) -> Bool {
   |> result.is_error
 }
 
-/// See if the first string starts with the second one.
+/// Checks whether the first string starts with the second one.
 ///
 /// ## Examples
 ///
@@ -226,7 +226,7 @@ pub fn contains(does haystack: String, contain needle: String) -> Bool {
 pub external fn starts_with(String, String) -> Bool =
   "gleam_stdlib" "string_starts_with"
 
-/// See if the first string ends with the second one.
+/// Checks whether the first string ends with the second one.
 ///
 /// ## Examples
 ///
@@ -236,7 +236,7 @@ pub external fn starts_with(String, String) -> Bool =
 pub external fn ends_with(String, String) -> Bool =
   "gleam_stdlib" "string_ends_with"
 
-/// Create a list of strings by splitting a given string on a given substring.
+/// Creates a list of strings by splitting a given string on a given substring.
 ///
 /// ## Examples
 ///
@@ -275,7 +275,7 @@ pub fn split_once(
   }
 }
 
-/// Create a new string by joining two strings together.
+/// 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)
@@ -293,7 +293,7 @@ pub fn append(to first: String, suffix second: String) -> String {
   |> string_builder.to_string
 }
 
-/// Create a new string by joining many strings together.
+/// 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)
@@ -310,7 +310,7 @@ pub fn concat(strings: List(String)) -> String {
   |> string_builder.to_string
 }
 
-/// Create a new string by repeating a string a given number of times.
+/// Creates a new string by repeating a string a given number of times.
 ///
 /// This function runs in linear time.
 ///
@@ -325,7 +325,7 @@ pub fn repeat(string: String, times times: Int) -> String {
   |> concat
 }
 
-/// Join many strings together with a given separator.
+/// Joins many strings together with a given separator.
 ///
 /// This function runs in linear time.
 ///
@@ -349,7 +349,7 @@ type Direction {
 external fn erl_pad(String, Int, Direction, String) -> String =
   "gleam_stdlib" "string_pad"
 
-/// Pad 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
 ///
@@ -366,7 +366,7 @@ pub fn pad_left(string: String, to length: Int, with pad_string: String) {
   erl_pad(string, length, Leading, pad_string)
 }
 
-/// Pad a string on the right until it has a given length.
+/// Pads a string on the right until it has a given length.
 ///
 /// ## Examples
 ///
@@ -386,7 +386,7 @@ pub fn pad_right(string: String, to length: Int, with pad_string: String) {
 external fn erl_trim(String, Direction) -> String =
   "string" "trim"
 
-/// Get rid of whitespace on both sides of a String.
+/// Removes whitespace on both sides of a String.
 ///
 /// ## Examples
 ///
@@ -397,7 +397,7 @@ pub fn trim(string: String) -> String {
   erl_trim(string, Both)
 }
 
-/// Get rid of whitespace on the left of a String.
+/// Removes whitespace on the left of a String.
 ///
 /// ## Examples
 ///
@@ -408,7 +408,7 @@ pub fn trim_left(string: String) -> String {
   erl_trim(string, Leading)
 }
 
-/// Get rid of whitespace on the right of a String.
+/// Removes whitespace on the right of a String.
 ///
 /// ## Examples
 ///
@@ -419,7 +419,7 @@ pub fn trim_right(string: String) -> String {
   erl_trim(string, Trailing)
 }
 
-/// Split a non-empty string into its head and tail. This lets you
+/// Splits a non-empty string into its head and tail. This lets you
 /// pattern match on strings exactly as you would with lists.
 ///
 /// ## Examples
@@ -434,7 +434,7 @@ pub external fn pop_grapheme(
 ) -> Result(tuple(String, String), Nil) =
   "gleam_stdlib" "string_pop_grapheme"
 
-/// Convert a string to a list of Graphemes.
+/// Converts a string to a list of Graphemes.
 ///
 ///    > to_graphemes("abc")
 ///    ["a", "b", "c"]
@@ -449,7 +449,7 @@ pub fn to_graphemes(string: String) -> List(String) {
 external fn int_to_utf_codepoint(Int) -> UtfCodepoint =
   "gleam_stdlib" "identity"
 
-/// Convert 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 5acf8e1..36970b2 100644
--- a/src/gleam/string_builder.gleam
+++ b/src/gleam/string_builder.gleam
@@ -11,21 +11,21 @@
 ///
 pub external type StringBuilder
 
-/// Prepend a String onto the start of some StringBuilder.
+/// Prepends a String onto the start of some StringBuilder.
 ///
 /// Runs in constant time.
 ///
 pub external fn prepend(to: StringBuilder, prefix: String) -> StringBuilder =
   "gleam_stdlib" "iodata_prepend"
 
-/// Append a String onto the end of some StringBuilder.
+/// Appends a String onto the end of some StringBuilder.
 ///
 /// Runs in constant time.
 ///
 pub external fn append(to: StringBuilder, suffix: String) -> StringBuilder =
   "gleam_stdlib" "iodata_append"
 
-/// Prepend some StringBuilder onto the start of another.
+/// Prepends some StringBuilder onto the start of another.
 ///
 /// Runs in constant time.
 ///
@@ -35,7 +35,7 @@ pub external fn prepend_builder(
 ) -> StringBuilder =
   "gleam_stdlib" "iodata_prepend"
 
-/// Append some StringBuilder onto the end of another.
+/// Appends some StringBuilder onto the end of another.
 ///
 /// Runs in constant time.
 ///
@@ -45,7 +45,7 @@ pub external fn append_builder(
 ) -> StringBuilder =
   "gleam_stdlib" "iodata_append"
 
-/// Convert a list of strings into a builder.
+/// Converts a list of strings into a builder.
 ///
 /// Runs in constant time.
 ///
@@ -59,7 +59,7 @@ pub external fn from_strings(List(String)) -> StringBuilder =
 pub external fn concat(List(StringBuilder)) -> StringBuilder =
   "gleam_stdlib" "identity"
 
-/// Convert a string into a builder.
+/// Converts a string into a builder.
 ///
 /// Runs in constant time.
 ///
@@ -132,7 +132,7 @@ pub fn replace(
   erl_replace(iodata, pattern, substitute, All)
 }
 
-/// Compare two builders to determine if they have the same textual content.
+/// Compares two builders to determine if they have the same textual content.
 ///
 /// 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
@@ -150,7 +150,7 @@ pub fn replace(
 pub external fn is_equal(StringBuilder, StringBuilder) -> Bool =
   "string" "equal"
 
-/// Inspect a builder to determine if it is equivalent to an empty string.
+/// Inspects a builder to determine if it is equivalent to an empty string.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/uri.gleam b/src/gleam/uri.gleam
index 2ff542a..10c4a7b 100644
--- a/src/gleam/uri.gleam
+++ b/src/gleam/uri.gleam
@@ -109,7 +109,7 @@ external fn erl_query_to_string(
 ) -> Dynamic =
   "uri_string" "compose_query"
 
-/// Encode a list of key value pairs as a URI query string.
+/// Encodes a list of key value pairs as a URI query string.
 ///
 /// The opposite operation is `uri.parse_query`.
 ///
@@ -120,7 +120,7 @@ pub fn query_to_string(query: List(tuple(String, String))) -> String {
   |> result.unwrap("")
 }
 
-/// Encode a string into a percent encoded representation.
+/// Encodes a string into a percent encoded representation.
 /// Note that this encodes space as +.
 ///
 /// ## Example
@@ -133,7 +133,7 @@ pub fn percent_encode(value: String) -> String {
   |> string.replace(each: "k=", with: "")
 }
 
-/// Decode a percent encoded string.
+/// Decodes a percent encoded string.
 ///
 /// ## Example
 ///
@@ -170,7 +170,7 @@ fn remove_dot_segments(input: List(String)) -> List(String) {
   do_remove_dot_segments(input, [])
 }
 
-/// Split the path section of a URI into it's constituent segments.
+/// Splits the path section of a URI into it's constituent segments.
 ///
 /// Removes empty segments and resolves dot-segments as specified in
 /// [section 5.2](https://www.ietf.org/rfc/rfc3986.html#section-5.2) of the RFC.
@@ -182,7 +182,7 @@ pub fn path_segments(path: String) -> List(String) {
 external fn erl_to_string(Map(UriKey, Dynamic)) -> Dynamic =
   "uri_string" "recompose"
 
-/// Encode a `Uri` value as a URI string.
+/// Encodes a `Uri` value as a URI string.
 ///
 /// The opposite operation is `uri.parse`.
 ///
@@ -213,7 +213,7 @@ pub fn to_string(uri: Uri) -> String {
   |> result.unwrap("")
 }
 
-/// Fetch the origin of a uri
+/// Fetches the origin of a uri
 ///
 /// Return the origin of a uri as defined in
 /// https://tools.ietf.org/html/rfc6454
@@ -239,7 +239,7 @@ fn join_segments(segments: List(String)) -> String {
   string.join(["", ..segments], "/")
 }
 
-/// Resolve 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 algorithm for merging uris is described in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-5.2)