From d28f3ba7e5f9bba604da85ebc5a482d0a233186a Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Thu, 29 Dec 2022 03:48:28 +0300
Subject: [PATCH] docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 README.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README.md b/README.md
index e39b375..d89dccf 100644
--- a/README.md
+++ b/README.md
@@ -758,8 +758,26 @@ Resulting array length is strictly equal to the longest input array length.
 
 Return an iterator/generator from the current array.
 
+```bnf
+<array>.iter()
+<array>.iter(<func>)
+<array>.iter(<func>, <onstop>)
+	-> <generator>
+
+<func>(<elem>, <index>)
+	-> <value>
+
+<onstop>(STOP, ...<args>)
+<onstop>(<value>, ...<args>)
+```
+
 This is mostly useful in combination with the [Generator extensions and utilities](#generator-extensions-and-utilities)
 
+Note that all stoppable functions/iterators support `<onstop>` callback as 
+the last argument.
+
+<!-- XXX document <onstop> in all applicable functions -->
+
 
 ### `<array>.between(..)`
 
@@ -820,6 +838,9 @@ a supporting iterator method will abort further execution and correctly exit.
 Like `Array`'s `.map(..)`, `.filter(..)`, `.reduce(..)` and `.forEach(..)` but 
 with added support for aborting iteration by throwing `STOP` or `STOP(<value>)`.
 
+These can be passed a `<onstop>` callback as an additional last argument 
+that will be called if `STOP`/`STOP(<value>)` is returned or thrown.
+
 
 ### Large `Array` iteration (chunked)
 
@@ -2304,6 +2325,10 @@ var L = [1,2,3,4,5]
         .toArray()
 ```
 
+These also support passing the `<onstop>` callback as additional last 
+argument. It will be called when `STOP`/`STOP(<value>)` is thrown or 
+returned.
+
 
 #### `<generator>.reduce(..)` / `<generator>.greduce(..)`