Make API documentation into YAML files and autogenerate markdown files

and manpages from those.

1 files changed, 2 insertions, 676 deletions

diff --git a/docs/lists.md b/docs/lists.md
index 141f6abd..dfb64aad 100644
--- a/docs/lists.md
+++ b/docs/lists.md
@@ -231,680 +231,6 @@ The TL;DR is: you can cheaply modify local variables that aren't aliased or
 `@`-allocated lists, but if you assign a local variable list to another
 variable or dereference a heap pointer, it may trigger copy-on-write behavior.
 
-## List Methods
-
-- [`func binary_search(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int)`](#binary_search)
-- [`func by(list: [T], step: Int -> [T])`](#by)
-- [`func clear(list: @[T] -> Void)`](#clear)
-- [`func counts(list: [T] -> {T=Int})`](#counts)
-- [`func find(list: [T], target: T -> Int?)`](#find)
-- [`func first(list: [T], predicate: func(item:&T -> Bool) -> Int)`](#first)
-- [`func from(list: [T], first: Int -> [T])`](#from)
-- [`func has(list: [T], element: T -> Bool)`](#has)
-- [`func heap_pop(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?)`](#heap_pop)
-- [`func heap_push(list: @[T], item: T, by=T.compare -> Void)`](#heap_push)
-- [`func heapify(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)`](#heapify)
-- [`func insert(list: @[T], item: T, at: Int = 0 -> Void)`](#insert)
-- [`func insert_all(list: @[T], items: [T], at: Int = 0 -> Void)`](#insert_all)
-- [`func pop(list: &[T], index: Int = -1 -> T?)`](#pop)
-- [`func random(list: [T], random: func(min,max:Int64->Int64)? = none -> T)`](#random)
-- [`func remove_at(list: @[T], at: Int = -1, count: Int = 1 -> Void)`](#remove_at)
-- [`func remove_item(list: @[T], item: T, max_count: Int = -1 -> Void)`](#remove_item)
-- [`func reversed(list: [T] -> [T])`](#reversed)
-- [`func sample(list: [T], count: Int, weights: [Num]? = ![Num], random: func(->Num)? = none -> [T])`](#sample)
-- [`func shuffle(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void)`](#shuffle)
-- [`func shuffled(list: [T], random: func(min,max:Int64->Int64)? = none -> [T])`](#shuffled)
-- [`func slice(list: [T], from: Int, to: Int -> [T])`](#slice)
-- [`func sort(list: @[T], by=T.compare -> Void)`](#sort)
-- [`sorted(list: [T], by=T.compare -> [T])`](#sorted)
-- [`to(list: [T], last: Int -> [T])`](#to)
-- [`unique(list: [T] -> {T})`](#unique)
-
-### `binary_search`
-Performs a binary search on a sorted list.
+# API
 
-```tomo
-func binary_search(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int)
-```
-
-- `list`: The sorted list to search.
-- `by`: The comparison function used to determine order. If not specified, the
-  default comparison function for the item type will be used.
-
-**Returns:**  
-Assuming the input list is sorted according to the given comparison function,
-return the index where the given item would be inserted to maintain the sorted
-order. That is, if the item is found, return its index, otherwise return the
-place where it would be found if it were inserted and the list were sorted.
-
-**Example:**  
-```tomo
->> [1, 3, 5, 7, 9].binary_search(5)
-= 3
-
->> [1, 3, 5, 7, 9].binary_search(-999)
-= 1
-
->> [1, 3, 5, 7, 9].binary_search(999)
-= 6
-```
-
----
-
-### `by`
-Creates a new list with elements spaced by the specified step value.
-
-```tomo
-func by(list: [T], step: Int -> [T])
-```
-
-- `list`: The original list.
-- `step`: The step value for selecting elements.
-
-**Returns:**  
-A new list with every `step`-th element from the original list.
-
-**Example:**  
-```tomo
->> [1, 2, 3, 4, 5, 6].by(2)
-= [1, 3, 5]
-```
-
----
-
-### `clear`
-Clears all elements from the list.
-
-```tomo
-func clear(list: @[T] -> Void)
-```
-
-- `list`: The mutable reference to the list to be cleared.
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
->> my_list.clear()
-```
-
----
-
-### `counts`
-Counts the occurrences of each element in the list.
-
-```tomo
-func counts(list: [T] -> {T=Int})
-```
-
-- `list`: The list to count elements in.
-
-**Returns:**  
-A table mapping each element to its count.
-
-**Example:**  
-```tomo
->> [10, 20, 30, 30, 30].counts()
-= {10=1, 20=1, 30=3}
-```
-
----
-
-### `find`
-Finds the index of the first occurrence of an element (if any).
-
-```tomo
-func find(list: [T], target: T -> Int?)
-```
-
-- `list`: The list to search through.
-- `item`: The item to find in the list.
-
-**Returns:**  
-The index of the first occurrence or `!Int` if not found.
-
-**Example:**  
-```tomo
->> [10, 20, 30, 40, 50].find(20)
-= 2 : Int?
-
->> [10, 20, 30, 40, 50].find(9999)
-= none : Int?
-```
-
----
-
-### `first`
-Find the index of the first item that matches a predicate function (if any).
-
-```tomo
-func first(list: [T], predicate: func(item:&T -> Bool) -> Int)
-```
-
-- `list`: The list to search through.
-- `predicate`: A function that returns `yes` if the item should be returned or
-  `no` if it should not.
-
-**Returns:**  
-Returns the index of the first item where the predicate is true or `!Int` if no
-item matches.
-
-**Example:**  
-```tomo
->> [4, 5, 6].find(func(i:&Int): i.is_prime())
-= 5 : Int?
->> [4, 6, 8].find(func(i:&Int): i.is_prime())
-= none : Int?
-```
-
----
-
-### `from`
-Returns a slice of the list starting from a specified index.
-
-```tomo
-func from(list: [T], first: Int -> [T])
-```
-
-- `list`: The original list.
-- `first`: The index to start from.
-
-**Returns:**  
-A new list starting from the specified index.
-
-**Example:**  
-```tomo
->> [10, 20, 30, 40, 50].from(3)
-= [30, 40, 50]
-```
-
----
-
-### `has`
-Checks if the list has an element.
-
-```tomo
-func has(list: [T], element: T -> Bool)
-```
-
-- `list`: The list to check.
-- `target`: The element to check for.
-
-**Returns:**  
-`yes` if the list has the target, `no` otherwise.
-
-**Example:**  
-```tomo
->> [10, 20, 30].has(20)
-= yes
-```
-
----
-
-### `heap_pop`
-Removes and returns the top element of a heap or `none` if the list is empty.
-By default, this is the *minimum* value in the heap.
-
-```tomo
-func heap_pop(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?)
-```
-
-- `list`: The mutable reference to the heap.
-- `by`: The comparison function used to determine order. If not specified, the
-  default comparison function for the item type will be used.
-
-**Returns:**  
-The removed top element of the heap or `none` if the list is empty.
-
-**Example:**  
-```tomo
->> my_heap := [30, 10, 20]
->> my_heap.heapify()
->> my_heap.heap_pop()
-= 10
-```
-
----
-
-### `heap_push`
-Adds an element to the heap and maintains the heap property. By default, this
-is a *minimum* heap.
-
-```tomo
-func heap_push(list: @[T], item: T, by=T.compare -> Void)
-```
-
-- `list`: The mutable reference to the heap.
-- `item`: The item to be added.
-- `by`: The comparison function used to determine order. If not specified, the
-  default comparison function for the item type will be used.
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
->> my_heap.heap_push(10)
-```
-
----
-
-### `heapify`
-Converts a list into a heap.
-
-```tomo
-func heapify(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)
-```
-
-- `list`: The mutable reference to the list to be heapified.
-- `by`: The comparison function used to determine order. If not specified, the
-  default comparison function for the item type will be used.
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
->> my_heap := [30, 10, 20]
->> my_heap.heapify()
-```
-
----
-
-### `insert`
-Inserts an element at a specified position in the list.
-
-```tomo
-func insert(list: @[T], item: T, at: Int = 0 -> Void)
-```
-
-- `list`: The mutable reference to the list.
-- `item`: The item to be inserted.
-- `at`: The index at which to insert the item (default is `0`). Since indices
-  are 1-indexed and negative indices mean "starting from the back", an index of
-  `0` means "after the last item".
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
->> list := [10, 20]
->> list.insert(30)
->> list
-= [10, 20, 30]
-
->> list.insert(999, at=2)
->> list
-= [10, 999, 20, 30]
-```
-
----
-
-### `insert_all`
-Inserts a list of items at a specified position in the list.
-
-```tomo
-func insert_all(list: @[T], items: [T], at: Int = 0 -> Void)
-```
-
-- `list`: The mutable reference to the list.
-- `items`: The items to be inserted.
-- `at`: The index at which to insert the item (default is `0`). Since indices
-  are 1-indexed and negative indices mean "starting from the back", an index of
-  `0` means "after the last item".
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
-list := [10, 20]
-list.insert_all([30, 40])
->> list
-= [10, 20, 30, 40]
-
-list.insert_all([99, 100], at=2)
->> list
-= [10, 99, 100, 20, 30, 40]
-```
-
----
-
-### `pop`
-Removes and returns an item from the list. If the given index is present in
-the list, the item at that index will be removed and the list will become one
-element shorter.
-
-```tomo
-func pop(list: &[T], index: Int = -1 -> T?)
-```
-
-- `list`: The list to remove an item from.
-- `index`: The index from which to remove the item (default: the last item).
-
-**Returns:**  
-`none` if the list is empty or the given index does not exist in the list,
-otherwise the item at the given index.
-
-**Example:**  
-```tomo
->> list := [10, 20, 30, 40]
-
->> list.pop()
-= 40
->> list
-= &[10, 20, 30]
-
->> list.pop(index=2)
-= 20
->> list
-= &[10, 30]
-```
-
----
-
-### `random`
-Selects a random element from the list.
-
-```tomo
-func random(list: [T], random: func(min,max:Int64->Int64)? = none -> T)
-```
-
-- `list`: The list from which to select a random element.
-- `random`: If provided, this function will be used to get a random index in the list. Returned
-  values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number
-  generation)
-
-**Returns:**  
-A random element from the list.
-
-**Example:**  
-```tomo
->> [10, 20, 30].random()
-= 20
-```
-
----
-
-### `remove_at`
-Removes elements from the list starting at a specified index.
-
-```tomo
-func remove_at(list: @[T], at: Int = -1, count: Int = 1 -> Void)
-```
-
-- `list`: The mutable reference to the list.
-- `at`: The index at which to start removing elements (default is `-1`, which means the end of the list).
-- `count`: The number of elements to remove (default is `1`).
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
-list := [10, 20, 30, 40, 50]
-list.remove_at(2)
->> list
-= [10, 30, 40, 50]
-
-list.remove_at(2, count=2)
->> list
-= [10, 50]
-```
-
----
-
-### `remove_item`
-Removes all occurrences of a specified item from the list.
-
-```tomo
-func remove_item(list: @[T], item: T, max_count: Int = -1 -> Void)
-```
-
-- `list`: The mutable reference to the list.
-- `item`: The item to be removed.
-- `max_count`: The maximum number of occurrences to remove (default is `-1`, meaning all occurrences).
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
-list := [10, 20, 10, 20, 30]
-list.remove_item(10)
->> list
-= [20, 20, 30]
-
-list.remove_item(20, max_count=1)
->> list
-= [20, 30]
-```
-
----
-
-### `reversed`
-Returns a reversed slice of the list.
-
-```tomo
-func reversed(list: [T] -> [T])
-```
-
-- `list`: The list to be reversed.
-
-**Returns:**  
-A slice of the list with elements in reverse order.
-
-**Example:**  
-```tomo
->> [10, 20, 30].reversed()
-= [30, 20, 10]
-```
-
----
-
-### `sample`
-Selects a sample of elements from the list, optionally with weighted
-probabilities.
-
-```tomo
-func sample(list: [T], count: Int, weights: [Num]? = ![Num], random: func(->Num)? = none -> [T])
-```
-
-- `list`: The list to sample from.
-- `count`: The number of elements to sample.
-- `weights`: The probability weights for each element in the list. These
-  values do not need to add up to any particular number, they are relative
-  weights. If no weights are given, elements will be sampled with uniform
-  probability.
-- `random`: If provided, this function will be used to get random values for
-  sampling the list. The provided function should return random numbers
-  between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic
-  pseudorandom number generation)
-
-**Errors:**
-Errors will be raised if any of the following conditions occurs:
-- The given list has no elements and `count >= 1`
-- `count < 0` (negative count)
-- The number of weights provided doesn't match the length of the list. 
-- Any weight in the weights list is negative, infinite, or `NaN`
-- The sum of the given weights is zero (zero probability for every element).
-
-**Returns:**  
-A list of sampled elements from the list.
-
-**Example:**  
-```tomo
->> [10, 20, 30].sample(2, weights=[90%, 5%, 5%])
-= [10, 10]
-```
-
----
-
-### `shuffle`
-Shuffles the elements of the list in place.
-
-```tomo
-func shuffle(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void)
-```
-
-- `list`: The mutable reference to the list to be shuffled.
-- `random`: If provided, this function will be used to get a random index in the list. Returned
-  values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number
-  generation)
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
->> list.shuffle()
-```
-
----
-
-### `shuffled`
-Creates a new list with elements shuffled.
-
-```tomo
-func shuffled(list: [T], random: func(min,max:Int64->Int64)? = none -> [T])
-```
-
-- `list`: The list to be shuffled.
-- `random`: If provided, this function will be used to get a random index in the list. Returned
-  values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number
-  generation)
-
-**Returns:**  
-A new list with shuffled elements.
-
-**Example:**  
-```tomo
->> [10, 20, 30, 40].shuffled()
-= [40, 10, 30, 20]
-```
-
----
-
-### `slice`
-Returns a slice of the list spanning the given indices (inclusive).
-
-```tomo
-func slice(list: [T], from: Int, to: Int -> [T])
-```
-
-- `list`: The original list.
-- `from`: The first index to include.
-- `to`: The last index to include.
-
-**Returns:**  
-A new list spanning the given indices. Note: negative indices are counted from
-the back of the list, so `-1` refers to the last element, `-2` the
-second-to-last, and so on.
-
-**Example:**  
-```tomo
->> [10, 20, 30, 40, 50].slice(2, 4)
-= [20, 30, 40]
-
->> [10, 20, 30, 40, 50].slice(-3, -2)
-= [30, 40]
-```
-
----
-
-### `sort`
-Sorts the elements of the list in place in ascending order (small to large).
-
-```tomo
-func sort(list: @[T], by=T.compare -> Void)
-```
-
-- `list`: The mutable reference to the list to be sorted.
-- `by`: The comparison function used to determine order. If not specified, the
-  default comparison function for the item type will be used.
-
-**Returns:**  
-Nothing.
-
-**Example:**  
-```tomo
-list := [40, 10, -30, 20]
-list.sort()
->> list
-= [-30, 10, 20, 40]
-
-list.sort(func(a,b:&Int): a.abs() <> b.abs())
->> list
-= [10, 20, -30, 40]
-```
-
----
-
-### `sorted`
-Creates a new list with elements sorted.
-
-```tomo
-func sorted(list: [T], by=T.compare -> [T])
-```
-
-- `list`: The list to be sorted.
-- `by`: The comparison function used to determine order. If not specified, the
-  default comparison function for the item type will be used.
-
-**Returns:**  
-A new list with sorted elements.
-
-**Example:**  
-```tomo
->> [40, 10, -30, 20].sorted()
-= [-30, 10, 20, 40]
-
->> [40, 10, -30, 20].sorted(func(a,b:&Int): a.abs() <> b.abs())
-= [10, 20, -30, 40]
-```
-
----
-
-### `to`
-Returns a slice of the list from the start of the original list up to a specified index (inclusive).
-
-```tomo
-func to(list: [T], last: Int -> [T])
-```
-
-- `list`: The original list.
-- `last`: The index up to which elements should be included.
-
-**Returns:**  
-A new list containing elements from the start up to the specified index.
-
-**Example:**  
-```tomo
->> [10, 20, 30, 40, 50].to(3)
-= [10, 20, 30]
-
->> [10, 20, 30, 40, 50].to(-2)
-= [10, 20, 30, 40]
-```
-
----
-
-### `unique`
-Returns a Set that contains the unique elements of the list.
-
-```tomo
-func unique(list: [T] -> |T|)
-```
-
-- `list`: The list to process.
-
-**Returns:**  
-A set containing only unique elements from the list.
-
-**Example:**  
-```tomo
->> [10, 20, 10, 10, 30].unique()
-= {10, 20, 30}
-```
+[API documentation](../api/lists.md)