From 4da5b32fdea1c59d36053f53b0314a7ca7783810 Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Wed, 14 Apr 2021 15:51:18 +0300
Subject: [PATCH] docs...

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

diff --git a/README.md b/README.md
index d57111b..3aa2a57 100644
--- a/README.md
+++ b/README.md
@@ -1247,8 +1247,29 @@ This can be useful when breaking recursive dependencies between promises or when
 it is simpler to thread the result receiver promise down the stack than building 
 a promise stack and manually threading the result up.
 
-<!-- XXX Example: show a clear use-case -- ping-pong?... -->
+<!-- 
+XXX Example: show a clear use-case -- entangled promises...
+-->
+Example: _entangled_ promises, resolving one will resolve the other
 ```javascript
+var a = Promise.cooperative()
+
+var b = new Promise(function(resolve, reject){
+        // we are finalized by a...
+        a.then(resolve, reject) 
+
+        // do something in competition with a...
+    })
+    // a is finalized by us...
+    .then(
+        function(res){
+            a.isSet
+                || a.set(res, true) 
+            return res }, 
+        function(res){
+            a.isSet
+                || a.set(res, false) 
+            return res })
 ```
 
 Note that functionally this can be considered a special-case of an 
@@ -1370,7 +1391,7 @@ And some disadvantages:
 #### `Promise.iter(..)` / `promise.IterablePromise(..)`
 
 Create an _iterable promise_
-```
+```bnf
 Promise.iter(<array>)
     -> <iterable-promise>
 ```