Improve documentation

8 files changed, 41 insertions, 37 deletions

diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index fa794d3..a9dff63 100644
--- a/src/gleam/int.gleam
+++ b/src/gleam/int.gleam
@@ -153,14 +153,16 @@ pub fn to_base36(int) {
 ///
 /// ## Examples
 ///
-///   > to_float(5)
-///   5.
+/// ```
+/// > to_float(5)
+/// 5.
 ///
-///   > to_float(0)
-///   0.
+/// > to_float(0)
+/// 0.
 ///
-///   > to_float(-3)
-///   -3.
+/// > to_float(-3)
+/// -3.
+/// ```
 ///
 pub fn to_float(int) {
   do_to_float(int)
diff --git a/src/gleam/iterator.gleam b/src/gleam/iterator.gleam
index 3c250c3..c2481ea 100644
--- a/src/gleam/iterator.gleam
+++ b/src/gleam/iterator.gleam
@@ -166,8 +166,10 @@ pub fn run(iterator: Iterator(e)) -> Nil {
 ///
 /// ## Examples
 ///
-///   > [1, 2, 3] |> from_list |> map(fn(x) { x * 2 }) |> to_list
-///   [2, 4, 6]
+/// ```
+/// > [1, 2, 3] |> from_list |> map(fn(x) { x * 2 }) |> to_list
+/// [2, 4, 6]
+/// ```
 ///
 pub fn to_list(iterator: Iterator(element)) -> List(element) {
   iterator
@@ -452,9 +454,9 @@ fn do_find(continuation: fn() -> Action(a), f: fn(a) -> Bool) -> Result(a, Nil)
 }
 
 /// Finds the first element in a given iterator for which the given function returns
-/// True.
+/// `True`.
 ///
-/// Returns `Error(Nil)` if the function does not return True for any of the
+/// Returns `Error(Nil)` if the function does not return `True` for any of the
 /// elements.
 ///
 /// ## Examples
@@ -781,7 +783,7 @@ fn do_intersperse(
   }
 }
 
-/// Creates an iterator that yields the given element
+/// Creates an iterator that yields the given `elem` element
 /// between elements emitted by the underlying iterator.
 ///
 /// ## Examples
@@ -920,7 +922,7 @@ pub fn group(
 /// This function acts similar to fold, but does not take an initial state.
 /// Instead, it starts from the first yielded element
 /// and combines it with each subsequent element in turn using the given function.
-/// The function is called as f(accumulator, current_element).
+/// The function is called as `f(accumulator, current_element)`.
 ///
 /// Returns `Ok` to indicate a successful run, and `Error` if called on an empty iterator.
 ///
@@ -1043,11 +1045,11 @@ fn do_fold_until(
 }
 
 /// Like `fold`, `fold_until` reduces an iterator of elements into a single value by calling a given
-/// function on each element in turn, but uses a `list.ContinueOrStop` to determine 
+/// function on each element in turn, but uses `list.ContinueOrStop` to determine
 /// whether or not to keep iterating.
 ///
 /// If called on an iterator of infinite length then this function will only ever
-/// return if the give function returns list.Stop.
+/// return if the function returns `list.Stop`.
 ///
 ///
 /// ## Examples
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index dadd9d9..5980d0f 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -509,7 +509,7 @@ pub fn flatten(lists: List(List(a))) -> List(a) {
   do_flatten(lists, [])
 }
 
-/// Map and flatten the result
+/// Maps the list with the given function and then flattens the result.
 ///
 /// ## Examples
 ///
@@ -777,7 +777,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.
+/// Takes two lists and returns a single list of 2-element tuples.
 ///
 /// If one of the lists is longer than the other, the remaining elements from
 /// the longer list are not used.
@@ -800,7 +800,7 @@ pub fn zip(xs: List(a), ys: List(b)) -> List(#(a, b)) {
   do_zip(xs, ys, [])
 }
 
-/// Takes two lists and returns a single list of 2 item tuples.
+/// Takes two lists and returns a single list of 2-element tuples.
 ///
 /// If one of the lists is longer than the other, an `Error` is returned.
 ///
@@ -835,7 +835,7 @@ fn do_unzip(input, xs, ys) {
   }
 }
 
-/// Takes a single list of 2 item tuples and returns two lists.
+/// Takes a single list of 2-element tuples and returns two lists.
 ///
 /// ## Examples
 ///
@@ -898,7 +898,7 @@ pub fn at(in list: List(a), get index: Int) -> Result(a, Nil) {
 
 /// Removes any duplicate elements from a given list.
 ///
-/// This function returns in log-linear time (n log n).
+/// This function returns in loglinear time.
 ///
 /// ## Examples
 ///
@@ -1066,7 +1066,7 @@ pub fn split_while(
   do_split_while(list, predicate, [])
 }
 
-/// Given a list of 2 element tuples, finds 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 and returns the second element.
 ///
 /// If no tuple is found with the given key then `Error(Nil)` is returned.
@@ -1168,7 +1168,7 @@ pub fn pop_map(
   do_pop_map(haystack, is_desired, [])
 }
 
-/// Given a list of 2 element tuples, finds 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.
 ///
@@ -1201,7 +1201,7 @@ pub fn key_pop(
   )
 }
 
-/// Given a list of 2 element tuples, inserts 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.
@@ -1451,7 +1451,7 @@ pub fn sized_chunk(in list: List(a), into count: Int) -> List(List(a)) {
 /// This function acts similar to fold, but does not take an initial state.
 /// Instead, it starts from the first element in the list
 /// and combines it with each subsequent element in turn using the given function.
-/// The function is called as fun(accumulator, current_element).
+/// The function is called as `fun(accumulator, current_element)`.
 ///
 /// Returns `Ok` to indicate a successful run, and `Error` if called on an empty list.
 ///
@@ -1521,7 +1521,7 @@ pub fn last(list: List(a)) -> Result(a, Nil) {
   |> reduce(fn(_, elem) { elem })
 }
 
-/// Return unique combinations of elements in the list
+/// Return unique combinations of elements in the list.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/map.gleam b/src/gleam/map.gleam
index ad3b184..f0a7f5d 100644
--- a/src/gleam/map.gleam
+++ b/src/gleam/map.gleam
@@ -272,7 +272,7 @@ if javascript {
 }
 
 /// Creates a new map from a given map, minus any entries that a given function
-/// returns False for.
+/// returns `False` for.
 ///
 /// ## Examples
 ///
diff --git a/src/gleam/option.gleam b/src/gleam/option.gleam
index daab337..20e85e9 100644
--- a/src/gleam/option.gleam
+++ b/src/gleam/option.gleam
@@ -11,7 +11,7 @@ pub type Option(a) {
   None
 }
 
-/// Combines a list of options into a single option.
+/// Combines a list of `Option`s 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`.
 ///
@@ -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
 ///
@@ -98,7 +98,7 @@ pub fn from_result(result: Result(a, e)) -> Option(a) {
   }
 }
 
-/// Extracts 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
 ///
@@ -115,11 +115,11 @@ 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
-/// option stays the same.
+/// If the `Option` is a `None` rather than `Some`, the function is not called and the
+/// `Option` stays the same.
 ///
 /// ## Examples
 ///
@@ -210,7 +210,7 @@ pub fn or(first: Option(a), second: Option(a)) -> Option(a) {
   }
 }
 
-/// Given a list of options,
+/// Given a list of `Option`s,
 /// returns only the values inside `Some`.
 ///
 /// ## Examples
diff --git a/src/gleam/queue.gleam b/src/gleam/queue.gleam
index 9d887d8..4dc69b8 100644
--- a/src/gleam/queue.gleam
+++ b/src/gleam/queue.gleam
@@ -1,6 +1,6 @@
 import gleam/list
 
-/// A queue is an order collection of elements. It is similar to a list, but
+/// A queue is an ordered collection of elements. It is similar to a list, but
 /// unlike a list elements can be added to or removed from either the front or
 /// the back in a performant fashion.
 ///
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index 9c25c85..cd80e2d 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -237,7 +237,7 @@ 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 any element is `Error` then returns the first error.
 ///
 /// ## Examples
 ///    > all([Ok(1), Ok(2)])
diff --git a/src/gleam/string.gleam b/src/gleam/string.gleam
index d54a0f6..c624a30 100644
--- a/src/gleam/string.gleam
+++ b/src/gleam/string.gleam
@@ -368,7 +368,7 @@ pub fn split(x: String, on substring: String) -> List(String) {
 
 /// Splits a `String` a single time on the given substring.
 ///
-/// Returns an error if substring not present.
+/// Returns an `Error` if substring not present.
 ///
 /// ## Examples
 ///
@@ -654,7 +654,7 @@ if javascript {
 
 /// Converts an integer to a `UtfCodepoint`.
 ///
-/// Returns an error if the integer does not represent a valid UTF codepoint.
+/// Returns an `Error` if the integer does not represent a valid UTF codepoint.
 ///
 pub fn utf_codepoint(value: Int) -> Result(UtfCodepoint, Nil) {
   case value {