Use consistent phrasing in function docs

Author: janpieper

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.
 ///

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.
 ///

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,22 +38,22 @@ 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.
 ///
 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.
 ///

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

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
 ///

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
 ///

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) =