Initial map documentation

6 files changed, 61 insertions, 15 deletions

diff --git a/src/gleam/dynamic.gleam b/src/gleam/dynamic.gleam
index 6bddfdf..0e54ae1 100644
--- a/src/gleam/dynamic.gleam
+++ b/src/gleam/dynamic.gleam
@@ -1,11 +1,10 @@
-/// `Dynamic` data is data that we don"t know the type of yet.
-/// We likely get data like this from interop with Erlang, or from
-/// IO with the outside world.
-
 import gleam/list as list_mod
 import gleam/atom
 import gleam/result
 
+/// `Dynamic` data is data that we don"t know the type of yet.
+/// We likely get data like this from interop with Erlang, or from
+/// IO with the outside world.
 pub external type Dynamic;
 
 /// Convert any Gleam data into `Dynamic` data.
diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index 9de1549..b02cd94 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -1,5 +1,3 @@
-/// A set of utility functions for working with `Float` values.
-
 import gleam/iodata
 import gleam/order.{Order}
 import gleam/result.{Option}
diff --git a/src/gleam/map.gleam b/src/gleam/map.gleam
index 0b5595c..9762cd0 100644
--- a/src/gleam/map.gleam
+++ b/src/gleam/map.gleam
@@ -2,15 +2,54 @@ import gleam/result
 import gleam/list
 import gleam/result.{Option}
 
-/// An Erlang map. See [the Erlang map module](https://erlang.org/doc/man/maps.html) for details
+/// A dictionary of keys and values.
+///
+/// Any type can be used for the keys and values of a map, but all the keys
+/// must be of the same type and all the values must be of the same type.
+///
+/// Each key can only be present in a map once.
+///
+/// Maps are not ordered in any way, and any unintentional ordering is not to
+/// be relied upon in your code.
+///
+/// See [the Erlang map module](https://erlang.org/doc/man/maps.html) for more
+/// information.
+///
 pub external type Map(key, value);
 
+/// Determine the number of key-value pairs in the map.
+/// This function runs in constant time and does not need to iterate the map.
+///
+/// ## Examples
+///
+/// ```
+/// new() |> size() == 0
+/// new() |> insert("key", "value") |> size() == 1
+/// ```
+///
 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
+/// each key-value pair in the map.
+///
+/// The tuples in the list have no specific order.
+///
+/// ## Examples
+///
+/// ```
+/// new() |> to_list() == []
+/// new() |> insert("key", 0) |> to_list() == [tuple("key", 0)]
+/// ```
+///
 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.
+///
+/// If two tuples have the same key the last one in the list will be the one
+/// that is present in the map.
+///
 pub external fn from_list(List(tuple(key, value))) -> Map(key, value)
   = "maps" "from_list"
 
diff --git a/src/gleam/order.gleam b/src/gleam/order.gleam
index 4b12af7..ce58db0 100644
--- a/src/gleam/order.gleam
+++ b/src/gleam/order.gleam
@@ -1,6 +1,5 @@
 /// Represents the result of a single comparison to determine the precise
 /// ordering of two values.
-
 pub type Order {
   Lt
   Eq
diff --git a/src/gleam/pair.gleam b/src/gleam/pair.gleam
index 5883328..54fea2f 100644
--- a/src/gleam/pair.gleam
+++ b/src/gleam/pair.gleam
@@ -1,5 +1,3 @@
-// A set of utility functions for working with 2-tuples, or pairs.
-
 /// Returns the first element in a pair.
 ///
 /// ## Examples
diff --git a/src/gleam/result.gleam b/src/gleam/result.gleam
index e4ea275..2558e57 100644
--- a/src/gleam/result.gleam
+++ b/src/gleam/result.gleam
@@ -1,12 +1,21 @@
 /// Result represents the result of something that may succeed or fail.
 /// `Ok` means it was successful, `Error` means it failed.
-
 pub type Result(success, error) =
   Result(success, error)
 
+/// Nil is a type used to represent the absence of something, similar to null
+/// or undefined in other languages.
+///
+/// Unlike some other languages values cannot be implicitly nil, value that may
+/// be absent is typically represented using `Result(TheType, Nil)`. This is
+/// such a common type that offer the `Option(TheType)` alias.
 pub type Nil =
   Nil
 
+/// A value that is either there or not there.
+pub type Option(value) =
+  Result(value, Nil)
+
 /// Returns whether the value is Ok
 ///
 pub fn is_ok(result: Result(a, e)) -> Bool {
@@ -81,10 +90,14 @@ pub fn unwrap(result: Result(a, e), or default: a) -> a {
   }
 }
 
-/// A value that is either there or not there
-pub type Option(value) =
-  Result(value, Nil)
-
+/// Another way of writing `Error(Nil)`.
+///
+/// ## Examples
+///
+/// ```
+/// none() == Error(Nil)
+/// ```
+///
 pub fn none() -> Option(a) {
   Error(Nil)
 }