@grain/stdlib 0.4.6 → 0.5.2

package/set.gr

@@ -13,22 +13,30 @@ record Bucket<t> {
   mut next: Option<Bucket<t>>,
 }
 
+/**
+ * @section Types: Type declarations included in the Set module.
+ */
+
 record Set<k> {
   mut size: Number,
   mut buckets: Array<Option<Bucket<k>>>,
 }
 
+/**
+ * @section Values: Functions for working with Sets.
+ */
+
 // TODO: This could take an `eq` function to custom comparisons
 /**
- * Creates a new empty set with an initial storage of the given length. As values are added or removed, the length may grow or shrink. Generally, you won't need to care about the length of your set and can use `Set.make()` instead.
+ * Creates a new empty set 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 set and can use `Set.make()` instead.
  *
- * @param storageLength: The initial storage length of the set
- * @returns An empty set with the given initial storage length
+ * @param size: The initial storage size of the set
+ * @returns An empty set with the given initial storage size
  * 
  * @since 0.3.0
  */
-export let makeSized = storageLength => {
-  let buckets = Array.make(storageLength, None)
+export let makeSized = size => {
+  let buckets = Array.make(size, None)
   { size: 0, buckets }
 }
 /**
@@ -201,10 +209,10 @@ export let remove = (key, set) => {
 }
 
 /**
- * Returns the number of values within the set.
+ * Provides the count of values within the set.
  *
  * @param set: The set to inspect
- * @returns The number of elements in the set
+ * @returns The count of elements in the set
  * 
  * @since 0.3.0
  */
@@ -243,7 +251,7 @@ let rec forEachBucket = (fn, node) => {
   match (node) {
     None => void,
     Some({ key, next }) => {
-      fn(key)
+      fn(key): Void
       forEachBucket(fn, next)
     },
   }
@@ -256,6 +264,7 @@ let rec forEachBucket = (fn, node) => {
  * @param set: The set to iterate
  * 
  * @since 0.3.0
+ * @history v0.5.0: Ensured the iterator function return type is always `Void`
  */
 export let forEach = (fn, set) => {
   let buckets = set.buckets

package/set.md

@@ -13,24 +13,20 @@ No other changes yet.
 import Set from "set"
 ```
 
-### Set.**Bucket**
+## Types
 
-```grain
-record Bucket<t> {
-  key: t,
-  next: Option<Bucket<t>>,
-}
-```
+Type declarations included in the Set module.
 
 ### Set.**Set**
 
 ```grain
-record Set<k> {
-  size: Number,
-  buckets: Array<Option<Bucket<k>>>,
-}
+type Set<k>
 ```
 
+## Values
+
+Functions for working with Sets.
+
 ### Set.**makeSized**
 
 <details disabled>
@@ -42,19 +38,19 @@ No other changes yet.
 makeSized : Number -> Set<a>
 ```
 
-Creates a new empty set with an initial storage of the given length. As values are added or removed, the length may grow or shrink. Generally, you won't need to care about the length of your set and can use `Set.make()` instead.
+Creates a new empty set 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 set and can use `Set.make()` instead.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`storageLength`|`Number`|The initial storage length of the set|
+|`size`|`Number`|The initial storage size of the set|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Set<a>`|An empty set with the given initial storage length|
+|`Set<a>`|An empty set with the given initial storage size|
 
 ### Set.**make**
 
@@ -152,7 +148,7 @@ No other changes yet.
 size : Set<a> -> Number
 ```
 
-Returns the number of values within the set.
+Provides the count of values within the set.
 
 Parameters:
 
@@ -164,7 +160,7 @@ Returns:
 
 |type|description|
 |----|-----------|
-|`Number`|The number of elements in the set|
+|`Number`|The count of elements in the set|
 
 ### Set.**isEmpty**
 
@@ -212,13 +208,20 @@ Parameters:
 
 ### Set.**forEach**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.3.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.0</code></td><td>Ensured the iterator function return type is always `Void`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-forEach : ((a -> b), Set<a>) -> Void
+forEach : ((a -> Void), Set<a>) -> Void
 ```
 
 Iterates the set, calling an iterator function on each element.
@@ -227,7 +230,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The iterator function to call with each element|
+|`fn`|`a -> Void`|The iterator function to call with each element|
 |`set`|`Set<a>`|The set to iterate|
 
 ### Set.**reduce**

package/stack.gr

@@ -33,7 +33,7 @@ export let make = () => {
  * Checks if the given stack contains no items.
  *
  * @param stack: The stack to check
- * @returns `true` if the stack has no items, and `false` otherwise
+ * @returns `true` if the stack has no items or `false` otherwise
  */
 export let isEmpty = stack => {
   match (stack) {
@@ -43,10 +43,10 @@ export let isEmpty = stack => {
 }
 
 /**
- * Returns `Some(item)` where `item` is the value at the top of the stack, and `None` otherwise.
+ * Provides the value at the top of the stack, if it exists.
  *
  * @param stack: The stack to inspect
- * @returns The value at the top of the stack, if it exists
+ * @returns `Some(value)` containing the value at the top of the stack or `None` otherwise.
  */
 export let peek = stack => {
   match (stack) {

package/stack.md

@@ -15,9 +15,7 @@ Type declarations included in the Stack module.
 ### Stack.**Stack**
 
 ```grain
-record Stack<a> {
-  data: List<a>,
-}
+type Stack<a>
 ```
 
 Stacks are immutable data structures that store their data in a List.
@@ -58,7 +56,7 @@ Returns:
 
 |type|description|
 |----|-----------|
-|`Bool`|`true` if the stack has no items, and `false` otherwise|
+|`Bool`|`true` if the stack has no items or `false` otherwise|
 
 ### Stack.**peek**
 
@@ -66,7 +64,7 @@ Returns:
 peek : Stack<a> -> Option<a>
 ```
 
-Returns `Some(item)` where `item` is the value at the top of the stack, and `None` otherwise.
+Provides the value at the top of the stack, if it exists.
 
 Parameters:
 
@@ -78,7 +76,7 @@ Returns:
 
 |type|description|
 |----|-----------|
-|`Option<a>`|The value at the top of the stack, if it exists|
+|`Option<a>`|`Some(value)` containing the value at the top of the stack or `None` otherwise.|
 
 ### Stack.**push**