length->size, documentation

3 files changed, 70 insertions, 9 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2794088..e7129ff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.4.0 - 2022-12-10
+
+- `array.length` was renamed to `array.size` to match Gleam conventions of size
+  being used when the operation is constant time.
+
 ## v0.3.0 - 2022-12-10
 
 - The `then` and `then_try` function in the `promise` module have been renamed
diff --git a/src/gleam/javascript/array.gleam b/src/gleam/javascript/array.gleam
index 9718fc8..19b860d 100644
--- a/src/gleam/javascript/array.gleam
+++ b/src/gleam/javascript/array.gleam
@@ -1,24 +1,80 @@
-// TODO: docs
-// TODO: labels
+/// A JavaScript array, in Gleam!
+///
+/// Unlike most data structures in Gleam this one is mutable.
+///
 pub external type Array(element)
 
+/// Convert a JavaScript array to a Gleam list.
+///
+/// Runs in linear time.
+///
 pub external fn to_list(Array(element)) -> List(element) =
   "../../gleam.mjs" "toList"
 
+/// Convert a Gleam list to a JavaScript array.
+///
+/// Runs in linear time.
+///
 pub external fn from_list(List(element)) -> Array(element) =
   "../../ffi.mjs" "toArray"
 
-pub external fn length(Array(element)) -> Int =
+/// Get the number of elements in the array.
+///
+/// Runs in constant time.
+///
+pub external fn size(Array(element)) -> Int =
   "../../ffi.mjs" "length"
 
-pub external fn map(Array(a), fn(a) -> b) -> Array(b) =
+/// Returns a new array containing only the elements of the first array after
+/// the function has been applied to each one.
+///
+/// Runs in linear time.
+///
+/// # Examples
+///
+/// ```gleam
+/// > map(from_list([2, 4, 6]), fn(x) { x * 2 })
+/// from_list([4, 8, 12])
+/// ```
+///
+pub external fn map(Array(a), with: fn(a) -> b) -> Array(b) =
   "../../ffi.mjs" "map"
 
-pub external fn fold(Array(e), a, fn(a, e) -> a) -> a =
+/// Reduces a list of elements into a single value by calling a given function
+/// on each element, going from left to right.
+///
+/// `fold(from_list([1, 2, 3]), 0, add)` is the equivalent of
+/// `add(add(add(0, 1), 2), 3)`.
+///
+/// Runs in linear time.
+///
+pub external fn fold(over: Array(e), from: a, with: fn(a, e) -> a) -> a =
   "../../ffi.mjs" "reduce"
 
-pub external fn fold_right(Array(e), a, fn(a, e) -> a) -> a =
+/// Reduces a list of elements into a single value by calling a given function
+/// on each element, going from right to left.
+///
+/// `fold_right(from_list([1, 2, 3]), 0, add)` is the equivalent of
+/// `add(add(add(0, 3), 2), 1)`.
+///
+/// Runs in linear time.
+///
+pub external fn fold_right(over: Array(e), from: a, with: fn(a, e) -> a) -> a =
   "../../ffi.mjs" "reduceRight"
 
+/// Get the element at the given index.
+///
+/// # Examples
+///
+/// ```gleam
+/// > get(from_list([2, 4, 6]), 1)
+/// Ok(4)
+/// ```
+///
+/// ```gleam
+/// > get(from_list([2, 4, 6]), 4)
+/// Error(Nil)
+/// ```
+///
 pub external fn get(Array(e), Int) -> Result(e, Nil) =
   "../../ffi.mjs" "index"
diff --git a/test/gleam/javascript/array_test.gleam b/test/gleam/javascript/array_test.gleam
index 6e8599c..fd609ea 100644
--- a/test/gleam/javascript/array_test.gleam
+++ b/test/gleam/javascript/array_test.gleam
@@ -12,14 +12,14 @@ pub fn to_and_from_list_test() {
     |> array.to_list
 }
 
-pub fn length_test() {
+pub fn size_test() {
   assert 0 =
     array.from_list([])
-    |> array.length
+    |> array.size
 
   assert 2 =
     array.from_list([1, 2])
-    |> array.length
+    |> array.size
 }
 
 pub fn map_test() {