List documentation

2 files changed, 109 insertions, 4 deletions

diff --git a/src/gleam/function.gleam b/src/gleam/function.gleam
index 0839def..c0d699d 100644
--- a/src/gleam/function.gleam
+++ b/src/gleam/function.gleam
@@ -1,18 +1,19 @@
-/// A set of utility higher-order functions for working with functions.
-
 /// Takes two functions and chains them together to form one function that takes
 /// the input from the first and returns the output of the second.
+///
 pub fn compose(fun1: fn(a) -> b, fun2: fn(b) -> c) -> fn(a) -> c {
   fn(a) { fun1(a) |> fun2 }
 }
 
 /// Takes a function that takes two arguments and returns a new function that
 /// takes the same two arguments, but in reverse order.
+///
 pub fn flip(fun: fn(a, b) -> c) -> fn(b, a) -> c {
   fn(b, a) { fun(a, b) }
 }
 
 /// A function that always returns its input value.
+///
 pub fn identity(x: a) -> a {
   x
 }
diff --git a/src/gleam/list.gleam b/src/gleam/list.gleam
index 271ef3b..89d5ca4 100644
--- a/src/gleam/list.gleam
+++ b/src/gleam/list.gleam
@@ -1,3 +1,26 @@
+//// Lists are an ordered sequence of elements and are one of the most common
+//// data types in Gleam.
+////
+//// New elements can be added and removed from the front of a list in
+//// constant time, while adding and removing from the end requires traversing
+//// the copying the whole list, so keep this in mind when designing your
+//// programs.
+////
+//// There is a dedicated syntax for prefixing to a list:
+////
+//// ```
+//// let new_list = [1, 2, ..existing_list]
+//// ```
+////
+//// And a matching syntax for getting the first elements of a list:
+////
+//// ```
+//// case list {
+////   [first_element, ..rest] -> first_element
+////   _ -> "this pattern matches when the list is empty"
+//// }
+//// ```
+
 import gleam/int
 import gleam/pair
 import gleam/order.{Order}
@@ -6,22 +29,80 @@ import gleam/result.{Option}
 pub type List(elements) =
   List(elements)
 
+/// An error value returned by the `strict_zip` function.
+///
 pub type LengthMismatch {
   LengthMismatch
 }
 
-/// Using the Erlang C BIF implementation.
+/// Count 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.
+///
+/// This function is natively implemented by the virtual machine and is highly
+/// optimised.
+///
+/// ## Examples
+///
+/// ```
+/// length([]) == 0
+/// length([1]) == 1
+/// length([1, 2]) == 2
+/// ```
 ///
 pub external fn length(of: List(a)) -> Int = "erlang" "length"
 
-/// Using the Erlang C BIF implementation.
+/// Create 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
+/// it runs in linear time.
+///
+/// This function is natively implemented by the virtual machine and is highly
+/// optimised.
+///
+/// ## Examples
+///
+/// ```
+/// reverse([]) == []
+/// reverse([1]) == [1]
+/// reverse([1, 2]) == [2, 1]
+/// ```
 ///
 pub external fn reverse(List(a)) -> List(a) = "lists" "reverse"
 
+/// Determine whether or not the list is empty.
+///
+/// This function runs in constant time.
+///
+/// ## Examples
+///
+/// ```
+/// is_empty([]) == True
+/// is_empty([1]) == False
+/// is_empty([1, 1]) == False
+/// ```
+///
 pub fn is_empty(list: List(a)) -> Bool {
   list == []
 }
 
+/// Determine 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.
+///
+/// ## Examples
+///
+/// ```
+/// contains([], 0) == True
+/// contains([0], 0) == True
+/// contains([1], 0) == False
+/// contains([1, 1], 0) == False
+/// contains([1, 0], 0) == True
+/// ```
+///
 pub fn contains(list: List(a), has elem: a) -> Bool {
   case list {
     [] -> False
@@ -29,6 +110,16 @@ pub fn contains(list: List(a), has elem: a) -> Bool {
   }
 }
 
+/// Get the first element from the start of the list, if there is one.
+///
+/// ## Examples
+///
+/// ```
+/// head([]) == Error(Nil)
+/// head([0]) == Ok(0)
+/// head([1, 2]) == Ok(1)
+/// ```
+///
 pub fn head(list: List(a)) -> Option(a) {
   case list {
     [] -> result.none()
@@ -36,6 +127,19 @@ pub fn head(list: List(a)) -> Option(a) {
   }
 }
 
+/// Get 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.
+///
+/// ## Examples
+///
+/// ```
+/// tail([]) == Error(Nil)
+/// tail([0]) == Ok([])
+/// tail([1, 2]) == Ok([2])
+/// ```
+///
 pub fn tail(list: List(a)) -> Option(List(a)) {
   case list {
     [] -> result.none()