From 2e735392d8ffc7c8739a51ab53b0793c7cd50818 Mon Sep 17 00:00:00 2001
From: Spotandjake <spotandjake@hotmail.com>
Date: Sun, 17 Nov 2024 20:14:39 -0500
Subject: [PATCH 1/4] chore(stdlib): Add examples to `Queue` module

---
 stdlib/queue.gr | 205 ++++++++++++++++++++++++++++-----
 stdlib/queue.md | 296 ++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 452 insertions(+), 49 deletions(-)

diff --git a/stdlib/queue.gr b/stdlib/queue.gr
index 0b605f054..326d9a7e1 100644
--- a/stdlib/queue.gr
+++ b/stdlib/queue.gr
@@ -7,6 +7,13 @@
  *
  * @example from "queue" include Queue
  *
+ * @example
+ * let queue = Queue.fromList([0, 1])
+ * Queue.push(2, queue)
+ * assert Queue.pop(queue) == Some(0)
+ * assert Queue.pop(queue) == Some(1)
+ * assert Queue.pop(queue) == Some(2)
+ *
  * @since v0.2.0
  */
 module Queue
@@ -33,6 +40,8 @@ abstract record Queue<a> {
  * @param size: The initial storage size of the queue
  * @returns An empty queue
  *
+ * @example Queue.make() // Creates a new queue
+ *
  * @since v0.6.0
  */
 provide let make = (size=16) => {
@@ -45,6 +54,9 @@ provide let make = (size=16) => {
  * @param queue: The queue to check
  * @returns `true` if the queue has no items or `false` otherwise
  *
+ * @example Queue.isEmpty(Queue.make()) == true
+ * @example Queue.isEmpty(Queue.fromList([1, 2])) == false
+ *
  * @since v0.6.0
  */
 provide let isEmpty = queue => queue.size == 0
@@ -55,6 +67,9 @@ provide let isEmpty = queue => queue.size == 0
  * @param queue: The queue to inspect
  * @returns The count of the items in the queue
  *
+ * @example Queue.size(Queue.make()) == 0
+ * @example Queue.size(Queue.fromList([1, 2])) == 2
+ *
  * @since v0.6.0
  */
 provide let size = queue => queue.size
@@ -65,6 +80,12 @@ provide let size = queue => queue.size
  * @param queue: The queue to inspect
  * @returns `Some(value)` containing the value at the beginning of the queue or `None` otherwise.
  *
+ * @example Queue.peek(Queue.make()) == None
+ * @example
+ * let queue = Queue.make()
+ * Queue.push(1, queue)
+ * assert Queue.peek(queue) == Some(1)
+ *
  * @since v0.6.0
  */
 provide let peek = queue => {
@@ -77,6 +98,12 @@ provide let peek = queue => {
  * @param value: The item to be added
  * @param queue: The queue being updated
  *
+ * @example
+ * let queue = Queue.make()
+ * assert Queue.peek(queue) == None
+ * Queue.push(1, queue)
+ * assert Queue.peek(queue) == Some(1)
+ *
  * @since v0.6.0
  */
 provide let push = (value, queue) => {
@@ -111,6 +138,12 @@ provide let push = (value, queue) => {
  * @param queue: The queue being updated
  * @returns The element removed from the queue
  *
+ * @example
+ * let queue = Queue.make()
+ * Queue.push(1, queue)
+ * assert Queue.pop(queue) == Some(1)
+ * assert Queue.pop(queue) == None
+ *
  * @since v0.6.0
  */
 provide let pop = queue => {
@@ -125,12 +158,60 @@ provide let pop = queue => {
   }
 }
 
+/**
+ * Clears the queue by removing all of its elements
+ *
+ * @param queue: The queue to clear
+ *
+ * @example
+ * let queue = Queue.make()
+ * Queue.push(1, queue)
+ * assert Queue.size(queue) == 1
+ * Queue.clear(queue)
+ * assert Queue.size(queue) == 0
+ *
+ * @since v0.6.0
+ */
+provide let clear = queue => {
+  queue.size = 0
+  Array.fill(None, queue.array)
+  queue.headIndex = 0
+  queue.tailIndex = 0
+}
+
+/**
+ * Produces a shallow copy of the input queue.
+ *
+ * @param queue: The queue to copy
+ * @returns A new queue containing the elements from the input
+ *
+ * @example
+ * let queue = Queue.make()
+ * Queue.push(1, queue)
+ * let copiedQueue = Queue.copy(queue)
+ * Queue.push(2, queue) // Does not affect copiedQueue
+ * assert Queue.pop(copiedQueue) == Some(1)
+ *
+ * @since v0.6.0
+ */
+provide let copy = queue => {
+  let { size, array, headIndex, tailIndex } = queue
+  { size, array: Array.copy(array), headIndex, tailIndex }
+}
+
 /**
  * Converts a queue into a list of its elements.
  *
  * @param queue: The queue to convert
  * @returns A list containing all queue values
  *
+ * @example
+ * let queue = Queue.make()
+ * Queue.push(0, queue)
+ * Queue.push(1, queue)
+ * Queue.push(2, queue)
+ * assert Queue.toList(queue) == [0, 1, 2]
+ *
  * @since v0.6.0
  */
 provide let toList = queue => {
@@ -152,6 +233,11 @@ provide let toList = queue => {
  * @param list: The list to convert
  * @returns A queue containing all list values
  *
+ * @example
+ * let queue = Queue.fromList([0, 1])
+ * assert Queue.pop(queue) == Some(0)
+ * assert Queue.pop(queue) == Some(1)
+ *
  * @since v0.6.0
  */
 provide let fromList = list => {
@@ -160,39 +246,19 @@ provide let fromList = list => {
   queue
 }
 
-/**
- * Clears the queue by removing all of its elements
- *
- * @param queue: The queue to clear
- *
- * @since v0.6.0
- */
-provide let clear = queue => {
-  queue.size = 0
-  Array.fill(None, queue.array)
-  queue.headIndex = 0
-  queue.tailIndex = 0
-}
-
-/**
- * Produces a shallow copy of the input queue.
- *
- * @param queue: The queue to copy
- * @returns A new queue containing the elements from the input
- *
- * @since v0.6.0
- */
-provide let copy = queue => {
-  let { size, array, headIndex, tailIndex } = queue
-  { size, array: Array.copy(array), headIndex, tailIndex }
-}
-
 /**
  * Converts a queue into an array of its values.
  *
  * @param queue: The queue to convert
  * @returns An array containing all values from the given queue
  *
+ * @example
+ * let queue = Queue.make()
+ * Queue.push(0, queue)
+ * Queue.push(1, queue)
+ * Queue.push(2, queue)
+ * assert Queue.toArray(queue) == [> 0, 1, 2]
+ *
  * @since v0.6.0
  */
 provide let toArray = queue => {
@@ -230,6 +296,11 @@ provide let toArray = queue => {
  * @param arr: The array to convert
  * @returns A queue containing all values from the array
  *
+ * @example
+ * let queue = Queue.fromArray([> 0, 1])
+ * assert Queue.pop(queue) == Some(0)
+ * assert Queue.pop(queue) == Some(1)
+ *
  * @since v0.6.0
  */
 provide let fromArray = arr => {
@@ -255,6 +326,18 @@ provide let fromArray = arr => {
  * @param queue2: The second queue to compare
  * @returns `true` if the queues are equivalent or `false` otherwise
  *
+ * @example
+ * use Queue.{ (==) }
+ * let queue1 = Queue.fromList([0, 1, 2])
+ * let queue2 = Queue.fromList([0, 1, 2])
+ * assert queue1 == queue2
+ *
+ * @example
+ * use Queue.{ (==) }
+ * let queue1 = Queue.fromList([0, 1, 2])
+ * let queue2 = Queue.fromList([0, 1, 3])
+ * assert !(queue1 == queue2)
+ *
  * @since v0.6.0
  */
 provide let (==) = (queue1, queue2) => {
@@ -276,10 +359,24 @@ provide let (==) = (queue1, queue2) => {
 
 /**
  * An immutable queue implementation.
+ *
+ * @example
+ * let queue = Immutable.Queue.fromList([0, 1])
+ * let queue = Immutable.Queue.push(2, queue)
+ * assert Immutable.Queue.peek(queue) == Some(0)
+ * let queue = Immutable.Queue.pop(queue)
+ * assert Immutable.Queue.peek(queue) == Some(1)
+ * ignore(Queue.Immutable.pop(queue)) // Does not affect the original queue
+ * assert Immutable.Queue.peek(queue) == Some(1)
+ *
+ * @since v0.6.0
  */
 provide module Immutable {
   /**
    * An immutable FIFO (first-in-first-out) data structure.
+   *
+   * @since v0.6.0
+   * @history v0.5.4: Originally a module root API
    */
   abstract record ImmutableQueue<a> {
     forwards: List<a>,
@@ -289,6 +386,10 @@ provide module Immutable {
   /**
    * An empty queue.
    *
+   * @example
+   * let queue = Queue.Immutable.empty
+   * assert Queue.Immutable.isEmpty(queue)
+   *
    * @since v0.6.0
    * @history v0.5.4: Originally a module root API
    */
@@ -303,6 +404,10 @@ provide module Immutable {
    * @param queue: The queue to check
    * @returns `true` if the given queue is empty or `false` otherwise
    *
+   * @example Queue.Immutable.isEmpty(Queue.Immutable.empty) == true
+   *
+   * @example Queue.Immutable.isEmpty(Queue.Immutable.fromList([1, 2])) == false
+   *
    * @since v0.6.0
    * @history v0.2.0: Originally a module root API
    */
@@ -319,6 +424,14 @@ provide module Immutable {
    * @param queue: The queue to inspect
    * @returns `Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty
    *
+   * @example
+   * let queue = Queue.Immutable.fromList([1, 2, 3])
+   * assert Queue.Immutable.peek(queue) == Some(1)
+   *
+   * @example
+   * let queue = Queue.Immutable.empty
+   * assert Queue.Immutable.peek(queue) == None
+   *
    * @since v0.6.0
    * @history v0.2.0: Originally named `head`
    * @history v0.3.2: Deprecated `head` function
@@ -339,6 +452,12 @@ provide module Immutable {
    * @param queue: The queue to update
    * @returns An updated queue
    *
+   * @example
+   * let queue = Queue.Immutable.fromList([1])
+   * assert Queue.Immutable.size(queue) == 1
+   * let queue = Queue.Immutable.push(2, queue)
+   * assert Queue.Immutable.size(queue) == 2
+   *
    * @since v0.6.0
    * @history v0.2.0: Originally named `enqueue`
    * @history v0.3.2: Deprecated `enqueue` function
@@ -358,6 +477,16 @@ provide module Immutable {
    * @param queue: The queue to change
    * @returns An updated queue
    *
+   * @example
+   * let queue = Queue.Immutable.fromList([1, 2, 3])
+   * let queue = Queue.Immutable.pop(queue)
+   * assert Queue.Immutable.peek(queue) == Some(2)
+   *
+   * @example
+   * let queue = Queue.Immutable.empty
+   * let queue = Queue.Immutable.pop(queue)
+   * assert Queue.Immutable.isEmpty(queue)
+   *
    * @since v0.6.0
    * @history v0.2.0: Originally named `dequeue`
    * @history v0.3.2: Deprecated `dequeue` function
@@ -381,6 +510,9 @@ provide module Immutable {
    * @param queue: The queue to inspect
    * @returns The number of values in the queue
    *
+   * @example Queue.Immutable.size(Queue.Immutable.empty) == 0
+   * @example Queue.Immutable.size(Queue.Immutable.fromList([1, 2])) == 2
+   *
    * @since v0.6.0
    * @history v0.3.2: Originally a module root API
    */
@@ -399,6 +531,20 @@ provide module Immutable {
    * @param queue: The queue to convert
    * @returns A list containing all queue values
    *
+   * @example
+   * let queue = Queue.Immutable.empty
+   * let queue = Queue.Immutable.push(1, queue)
+   * let queue = Queue.Immutable.push(2, queue)
+   * assert Queue.Immutable.toList(queue) == [1, 2]
+   *
+   * @example
+   * let queue = Queue.Immutable.fromList([1, 2, 3])
+   * assert Queue.Immutable.toList(queue) == [1, 2, 3]
+   *
+   * @example
+   * let queue = Queue.Immutable.empty
+   * assert Queue.Immutable.toList(queue) == []
+   *
    * @since v0.6.0
    */
   provide let toList = queue => {
@@ -411,6 +557,11 @@ provide module Immutable {
    * @param list: The list to convert
    * @returns A queue containing all list values
    *
+   * @example
+   * let queue = Queue.Immutable.fromList([1, 2, 3])
+   * assert Queue.Immutable.peek(queue) == Some(1)
+   * assert Queue.Immutable.size(queue) == 3
+   *
    * @since v0.6.0
    */
   provide let fromList = list => {
diff --git a/stdlib/queue.md b/stdlib/queue.md
index d2dc23c34..e5e5ec689 100644
--- a/stdlib/queue.md
+++ b/stdlib/queue.md
@@ -17,6 +17,14 @@ No other changes yet.
 from "queue" include Queue
 ```
 
+```grain
+let queue = Queue.fromList([0, 1])
+Queue.push(2, queue)
+assert Queue.pop(queue) == Some(0)
+assert Queue.pop(queue) == Some(1)
+assert Queue.pop(queue) == Some(2)
+```
+
 ## Types
 
 Type declarations included in the Queue module.
@@ -61,6 +69,12 @@ Returns:
 |----|-----------|
 |`Queue<a>`|An empty queue|
 
+Examples:
+
+```grain
+Queue.make() // Creates a new queue
+```
+
 ### Queue.**isEmpty**
 
 <details disabled>
@@ -86,6 +100,16 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the queue has no items or `false` otherwise|
 
+Examples:
+
+```grain
+Queue.isEmpty(Queue.make()) == true
+```
+
+```grain
+Queue.isEmpty(Queue.fromList([1, 2])) == false
+```
+
 ### Queue.**size**
 
 <details disabled>
@@ -111,6 +135,16 @@ Returns:
 |----|-----------|
 |`Number`|The count of the items in the queue|
 
+Examples:
+
+```grain
+Queue.size(Queue.make()) == 0
+```
+
+```grain
+Queue.size(Queue.fromList([1, 2])) == 2
+```
+
 ### Queue.**peek**
 
 <details disabled>
@@ -136,6 +170,18 @@ Returns:
 |----|-----------|
 |`Option<a>`|`Some(value)` containing the value at the beginning of the queue or `None` otherwise.|
 
+Examples:
+
+```grain
+Queue.peek(Queue.make()) == None
+```
+
+```grain
+let queue = Queue.make()
+Queue.push(1, queue)
+assert Queue.peek(queue) == Some(1)
+```
+
 ### Queue.**push**
 
 <details disabled>
@@ -156,6 +202,15 @@ Parameters:
 |`value`|`a`|The item to be added|
 |`queue`|`Queue<a>`|The queue being updated|
 
+Examples:
+
+```grain
+let queue = Queue.make()
+assert Queue.peek(queue) == None
+Queue.push(1, queue)
+assert Queue.peek(queue) == Some(1)
+```
+
 ### Queue.**pop**
 
 <details disabled>
@@ -181,7 +236,16 @@ Returns:
 |----|-----------|
 |`Option<a>`|The element removed from the queue|
 
-### Queue.**toList**
+Examples:
+
+```grain
+let queue = Queue.make()
+Queue.push(1, queue)
+assert Queue.pop(queue) == Some(1)
+assert Queue.pop(queue) == None
+```
+
+### Queue.**clear**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.6.0</code></summary>
@@ -189,24 +253,28 @@ No other changes yet.
 </details>
 
 ```grain
-toList : (queue: Queue<a>) => List<a>
+clear : (queue: Queue<a>) => Void
 ```
 
-Converts a queue into a list of its elements.
+Clears the queue by removing all of its elements
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`queue`|`Queue<a>`|The queue to convert|
+|`queue`|`Queue<a>`|The queue to clear|
 
-Returns:
+Examples:
 
-|type|description|
-|----|-----------|
-|`List<a>`|A list containing all queue values|
+```grain
+let queue = Queue.make()
+Queue.push(1, queue)
+assert Queue.size(queue) == 1
+Queue.clear(queue)
+assert Queue.size(queue) == 0
+```
 
-### Queue.**fromList**
+### Queue.**copy**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.6.0</code></summary>
@@ -214,24 +282,34 @@ No other changes yet.
 </details>
 
 ```grain
-fromList : (list: List<a>) => Queue<a>
+copy : (queue: Queue<a>) => Queue<a>
 ```
 
-Creates a queue from a list.
+Produces a shallow copy of the input queue.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`list`|`List<a>`|The list to convert|
+|`queue`|`Queue<a>`|The queue to copy|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Queue<a>`|A queue containing all list values|
+|`Queue<a>`|A new queue containing the elements from the input|
 
-### Queue.**clear**
+Examples:
+
+```grain
+let queue = Queue.make()
+Queue.push(1, queue)
+let copiedQueue = Queue.copy(queue)
+Queue.push(2, queue) // Does not affect copiedQueue
+assert Queue.pop(copiedQueue) == Some(1)
+```
+
+### Queue.**toList**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.6.0</code></summary>
@@ -239,18 +317,34 @@ No other changes yet.
 </details>
 
 ```grain
-clear : (queue: Queue<a>) => Void
+toList : (queue: Queue<a>) => List<a>
 ```
 
-Clears the queue by removing all of its elements
+Converts a queue into a list of its elements.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`queue`|`Queue<a>`|The queue to clear|
+|`queue`|`Queue<a>`|The queue to convert|
 
-### Queue.**copy**
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<a>`|A list containing all queue values|
+
+Examples:
+
+```grain
+let queue = Queue.make()
+Queue.push(0, queue)
+Queue.push(1, queue)
+Queue.push(2, queue)
+assert Queue.toList(queue) == [0, 1, 2]
+```
+
+### Queue.**fromList**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.6.0</code></summary>
@@ -258,22 +352,30 @@ No other changes yet.
 </details>
 
 ```grain
-copy : (queue: Queue<a>) => Queue<a>
+fromList : (list: List<a>) => Queue<a>
 ```
 
-Produces a shallow copy of the input queue.
+Creates a queue from a list.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`queue`|`Queue<a>`|The queue to copy|
+|`list`|`List<a>`|The list to convert|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Queue<a>`|A new queue containing the elements from the input|
+|`Queue<a>`|A queue containing all list values|
+
+Examples:
+
+```grain
+let queue = Queue.fromList([0, 1])
+assert Queue.pop(queue) == Some(0)
+assert Queue.pop(queue) == Some(1)
+```
 
 ### Queue.**toArray**
 
@@ -300,6 +402,16 @@ Returns:
 |----|-----------|
 |`Array<a>`|An array containing all values from the given queue|
 
+Examples:
+
+```grain
+let queue = Queue.make()
+Queue.push(0, queue)
+Queue.push(1, queue)
+Queue.push(2, queue)
+assert Queue.toArray(queue) == [> 0, 1, 2]
+```
+
 ### Queue.**fromArray**
 
 <details disabled>
@@ -325,6 +437,14 @@ Returns:
 |----|-----------|
 |`Queue<a>`|A queue containing all values from the array|
 
+Examples:
+
+```grain
+let queue = Queue.fromArray([> 0, 1])
+assert Queue.pop(queue) == Some(0)
+assert Queue.pop(queue) == Some(1)
+```
+
 ### Queue.**(==)**
 
 <details disabled>
@@ -351,16 +471,59 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the queues are equivalent or `false` otherwise|
 
+Examples:
+
+```grain
+use Queue.{ (==) }
+let queue1 = Queue.fromList([0, 1, 2])
+let queue2 = Queue.fromList([0, 1, 2])
+assert queue1 == queue2
+```
+
+```grain
+use Queue.{ (==) }
+let queue1 = Queue.fromList([0, 1, 2])
+let queue2 = Queue.fromList([0, 1, 3])
+assert !(queue1 == queue2)
+```
+
 ## Queue.Immutable
 
 An immutable queue implementation.
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+let queue = Immutable.Queue.fromList([0, 1])
+let queue = Immutable.Queue.push(2, queue)
+assert Immutable.Queue.peek(queue) == Some(0)
+let queue = Immutable.Queue.pop(queue)
+assert Immutable.Queue.peek(queue) == Some(1)
+ignore(Queue.Immutable.pop(queue)) // Does not affect the original queue
+assert Immutable.Queue.peek(queue) == Some(1)
+```
+
 ### Types
 
 Type declarations included in the Queue.Immutable module.
 
 #### Queue.Immutable.**ImmutableQueue**
 
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.4</code></td><td>Originally a module root API</td></tr>
+</tbody>
+</table>
+</details>
+
 ```grain
 type ImmutableQueue<a>
 ```
@@ -391,6 +554,13 @@ empty : ImmutableQueue<a>
 
 An empty queue.
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.empty
+assert Queue.Immutable.isEmpty(queue)
+```
+
 #### Queue.Immutable.**isEmpty**
 
 <details>
@@ -423,6 +593,16 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the given queue is empty or `false` otherwise|
 
+Examples:
+
+```grain
+Queue.Immutable.isEmpty(Queue.Immutable.empty) == true
+```
+
+```grain
+Queue.Immutable.isEmpty(Queue.Immutable.fromList([1, 2])) == false
+```
+
 #### Queue.Immutable.**peek**
 
 <details>
@@ -458,6 +638,18 @@ Returns:
 |----|-----------|
 |`Option<a>`|`Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.fromList([1, 2, 3])
+assert Queue.Immutable.peek(queue) == Some(1)
+```
+
+```grain
+let queue = Queue.Immutable.empty
+assert Queue.Immutable.peek(queue) == None
+```
+
 #### Queue.Immutable.**push**
 
 <details>
@@ -494,6 +686,15 @@ Returns:
 |----|-----------|
 |`ImmutableQueue<a>`|An updated queue|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.fromList([1])
+assert Queue.Immutable.size(queue) == 1
+let queue = Queue.Immutable.push(2, queue)
+assert Queue.Immutable.size(queue) == 2
+```
+
 #### Queue.Immutable.**pop**
 
 <details>
@@ -529,6 +730,20 @@ Returns:
 |----|-----------|
 |`ImmutableQueue<a>`|An updated queue|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.fromList([1, 2, 3])
+let queue = Queue.Immutable.pop(queue)
+assert Queue.Immutable.peek(queue) == Some(2)
+```
+
+```grain
+let queue = Queue.Immutable.empty
+let queue = Queue.Immutable.pop(queue)
+assert Queue.Immutable.isEmpty(queue)
+```
+
 #### Queue.Immutable.**size**
 
 <details>
@@ -561,6 +776,16 @@ Returns:
 |----|-----------|
 |`Number`|The number of values in the queue|
 
+Examples:
+
+```grain
+Queue.Immutable.size(Queue.Immutable.empty) == 0
+```
+
+```grain
+Queue.Immutable.size(Queue.Immutable.fromList([1, 2])) == 2
+```
+
 #### Queue.Immutable.**toList**
 
 <details disabled>
@@ -586,6 +811,25 @@ Returns:
 |----|-----------|
 |`List<a>`|A list containing all queue values|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.empty
+let queue = Queue.Immutable.push(1, queue)
+let queue = Queue.Immutable.push(2, queue)
+assert Queue.Immutable.toList(queue) == [1, 2]
+```
+
+```grain
+let queue = Queue.Immutable.fromList([1, 2, 3])
+assert Queue.Immutable.toList(queue) == [1, 2, 3]
+```
+
+```grain
+let queue = Queue.Immutable.empty
+assert Queue.Immutable.toList(queue) == []
+```
+
 #### Queue.Immutable.**fromList**
 
 <details disabled>
@@ -611,3 +855,11 @@ Returns:
 |----|-----------|
 |`ImmutableQueue<a>`|A queue containing all list values|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.fromList([1, 2, 3])
+assert Queue.Immutable.peek(queue) == Some(1)
+assert Queue.Immutable.size(queue) == 3
+```
+

From 42b6a49d4bb9d9bb7bd9f8239f3c4a7f623a9ddb Mon Sep 17 00:00:00 2001
From: Spotandjake <spotandjake@hotmail.com>
Date: Sun, 17 Nov 2024 20:27:32 -0500
Subject: [PATCH 2/4] chore: Correct wording in `make`

---
 stdlib/queue.gr | 3 ++-
 stdlib/queue.md | 6 +++++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/stdlib/queue.gr b/stdlib/queue.gr
index 326d9a7e1..8a053098e 100644
--- a/stdlib/queue.gr
+++ b/stdlib/queue.gr
@@ -34,13 +34,14 @@ abstract record Queue<a> {
 /**
  * Creates a new queue with an initial storage of the given size. As values are
  * added or removed, the internal storage may grow or shrink. Generally, you
- * won’t need to care about the storage size of your map and can use the
+ * won’t need to care about the storage size of your queue and can use the
  * default size.
  *
  * @param size: The initial storage size of the queue
  * @returns An empty queue
  *
  * @example Queue.make() // Creates a new queue
+ * @example Queue.make(size=16) // Creates a new queue with an initial size of 16
  *
  * @since v0.6.0
  */
diff --git a/stdlib/queue.md b/stdlib/queue.md
index e5e5ec689..92cb9bf8a 100644
--- a/stdlib/queue.md
+++ b/stdlib/queue.md
@@ -54,7 +54,7 @@ make : (?size: Number) => Queue<a>
 
 Creates a new queue with an initial storage of the given size. As values are
 added or removed, the internal storage may grow or shrink. Generally, you
-won’t need to care about the storage size of your map and can use the
+won’t need to care about the storage size of your queue and can use the
 default size.
 
 Parameters:
@@ -75,6 +75,10 @@ Examples:
 Queue.make() // Creates a new queue
 ```
 
+```grain
+Queue.make(size=16) // Creates a new queue with an initial size of 16
+```
+
 ### Queue.**isEmpty**
 
 <details disabled>

From f489b032d74eeefeddb8e49ee1fc4229ec6062d0 Mon Sep 17 00:00:00 2001
From: Spotandjake <40705786+spotandjake@users.noreply.github.com>
Date: Sat, 28 Dec 2024 21:14:11 -0500
Subject: [PATCH 3/4] Apply suggestions from oscar code review

Co-authored-by: Oscar Spencer <oscar.spen@gmail.com>
---
 stdlib/queue.gr | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/stdlib/queue.gr b/stdlib/queue.gr
index 8a053098e..d0bd48cda 100644
--- a/stdlib/queue.gr
+++ b/stdlib/queue.gr
@@ -160,7 +160,7 @@ provide let pop = queue => {
 }
 
 /**
- * Clears the queue by removing all of its elements
+ * Clears the queue by removing all of its elements.
  *
  * @param queue: The queue to clear
  *

From b9d25605007b2b5f23d9a49464efa2d3af21acd7 Mon Sep 17 00:00:00 2001
From: Spotandjake <spotandjake@hotmail.com>
Date: Sat, 28 Dec 2024 21:14:43 -0500
Subject: [PATCH 4/4] chore: Update grain doc

---
 stdlib/queue.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/stdlib/queue.md b/stdlib/queue.md
index 92cb9bf8a..0fcf9bfb9 100644
--- a/stdlib/queue.md
+++ b/stdlib/queue.md
@@ -260,7 +260,7 @@ No other changes yet.
 clear : (queue: Queue<a>) => Void
 ```
 
-Clears the queue by removing all of its elements
+Clears the queue by removing all of its elements.
 
 Parameters: