From 67fd3c725e6511adf70345f0733ec0b948477a11 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sat, 19 Apr 2025 14:35:34 -0400
Subject: Make API documentation into YAML files and autogenerate markdown
 files and manpages from those.

---
 api/sets.yaml | 221 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 221 insertions(+)
 create mode 100644 api/sets.yaml

(limited to 'api/sets.yaml')

diff --git a/api/sets.yaml b/api/sets.yaml
new file mode 100644
index 00000000..19d30f1d
--- /dev/null
+++ b/api/sets.yaml
@@ -0,0 +1,221 @@
+Set.add:
+  description: >
+    Adds an item to the set.
+  return:
+    type: 'Void'
+    description: >
+      Nothing.
+  args:
+    set:
+      type: '|T|'
+      description: >
+        The mutable reference to the set.
+    item:
+      type: 'T'
+      description: >
+        The item to add to the set.
+  example: |
+    >> nums.add(42)
+    
+Set.add_all:
+  description: >
+    Adds multiple items to the set.
+  return:
+    type: 'Void'
+    description: >
+      Nothing.
+  args:
+    set:
+      type: '@|T|'
+      description: >
+        The mutable reference to the set.
+    items:
+      type: '[T]'
+      description: >
+        The list of items to add to the set.
+  example: |
+    >> nums.add_all([1, 2, 3])
+    
+Set.clear:
+  description: >
+    Removes all items from the set.
+  return:
+    type: 'Void'
+    description: >
+      Nothing.
+  args:
+    set:
+      type: '@|T|'
+      description: >
+        The mutable reference to the set.
+  example: |
+    >> nums.clear()
+    
+Set.has:
+  description: >
+    Checks if the set contains a specified item.
+  return:
+    type: 'Bool'
+    description: >
+      `yes` if the item is present, `no` otherwise.
+  args:
+    set:
+      type: '|T|'
+      description: >
+        The set to check.
+    item:
+      type: 'T'
+      description: >
+        The item to check for presence.
+  example: |
+    >> |10, 20|.has(20)
+    = yes
+    
+Set.is_subset_of:
+  description: >
+    Checks if the set is a subset of another set.
+  return:
+    type: 'Bool'
+    description: >
+      `yes` if the set is a subset of the other set (strictly or not), `no` otherwise.
+  args:
+    set:
+      type: '|T|'
+      description: >
+        The set to check.
+    other:
+      type: '|T|'
+      description: >
+        The set to compare against.
+    strict:
+      type: 'Bool'
+      default: 'no'
+      description: >
+        If `yes`, checks if the set is a strict subset (does not equal the other set).
+  example: |
+    >> |1, 2|.is_subset_of(|1, 2, 3|)
+    = yes
+    
+Set.is_superset_of:
+  description: >
+    Checks if the set is a superset of another set.
+  return:
+    type: 'Bool'
+    description: >
+      `yes` if the set is a superset of the other set (strictly or not), `no` otherwise.
+  args:
+    set:
+      type: '|T|'
+      description: >
+        The set to check.
+    other:
+      type: '|T|'
+      description: >
+        The set to compare against.
+    strict:
+      type: 'Bool'
+      default: 'no'
+      description: >
+        If `yes`, checks if the set is a strict superset (does not equal the other set).
+  example: |
+    >> |1, 2, 3|.is_superset_of(|1, 2|)
+    = yes
+    
+Set.overlap:
+  description: >
+    Creates a new set with items that are in both the original set and another set.
+  return:
+    type: '|T|'
+    description: >
+      A new set containing only items present in both sets.
+  args:
+    set:
+      type: '|T|'
+      description: >
+        The original set.
+    other:
+      type: '|T|'
+      description: >
+        The set to intersect with.
+  example: |
+    >> |1, 2|.overlap(|2, 3|)
+    = |2|
+    
+Set.remove:
+  description: >
+    Removes an item from the set.
+  return:
+    type: 'Void'
+    description: >
+      Nothing.
+  args:
+    set:
+      type: '@|T|'
+      description: >
+        The mutable reference to the set.
+    item:
+      type: 'T'
+      description: >
+        The item to remove from the set.
+  example: |
+    >> nums.remove(42)
+    
+Set.remove_all:
+  description: >
+    Removes multiple items from the set.
+  return:
+    type: 'Void'
+    description: >
+      Nothing.
+  args:
+    set:
+      type: '@|T|'
+      description: >
+        The mutable reference to the set.
+    items:
+      type: '[T]'
+      description: >
+        The list of items to remove from the set.
+  example: |
+    >> nums.remove_all([1, 2, 3])
+    
+Set.with:
+  description: >
+    Creates a new set that is the union of the original set and another set.
+  return:
+    type: '|T|'
+    description: >
+      A new set containing all items from both sets.
+  args:
+    set:
+      type: '|T|'
+      description: >
+        The original set.
+    other:
+      type: '|T|'
+      description: >
+        The set to union with.
+  example: |
+    >> |1, 2|.with(|2, 3|)
+    = |1, 2, 3|
+    
+Set.without:
+  description: >
+    Creates a new set with items from the original set but without items from another set.
+  return:
+    type: '|T|'
+    description: >
+      A new set containing items from the original set excluding those in the other set.
+  args:
+    set:
+      type: '|T|'
+      description: >
+        The original set.
+    other:
+      type: '|T|'
+      description: >
+        The set of items to remove from the original set.
+  example: |
+    >> |1, 2|.without(|2, 3|)
+    = |1|
+    
-- 
cgit v1.2.3