docs and some cleanup...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

Promise.js

@@ -160,19 +160,8 @@ object.Constructor('IterablePromise', Promise, {
 				.reverse(),
 			'raw') },
 
-	// XXX do we need these?
-	// 			.pop()
-	// 			.shift()
-	// 			.first() / .last()
-	// 		...would be nice if these could stop everything that's not
-	// 		needed to execute...
-	// XXX these can change the "resolved" state...
-	// 		...i.e. return a pending promise when called from a fulfilled 
-	// 		promise....
-	// 			.concat(..)
-	// 			.push(..)
-	// 			.unshift(..)
-	// 			.first(..) / .last(..)
+	// NOTE: these can create an unresolved promise from a resolved 
+	// 		promise...
 	// XXX EXPEREMENTAL...
 	// 		....can we remove a level of indirection here???
 	// 		would be better to use the raw mode...
@@ -199,11 +188,17 @@ object.Constructor('IterablePromise', Promise, {
 				'raw') },
 	push: function(elem){
 		return this.concat([elem]) },
-	// XXX this can be written in the same style as .concat(..)
 	unshift: function(elem){
 		return this.constructor([elem])
 			.concat(this) },
 
+	// XXX do we need these?
+	// 			.pop()
+	// 			.shift()
+	// 			.first() / .last()
+	// 		...would be nice if these could stop everything that's not
+	// 		needed to execute...
+	
 
 	// Overload .then(..), .catch(..) and .finally(..) to return a plain 
 	// Promise instnace...

README.md

@@ -75,6 +75,8 @@ Library of JavaScript type extensions, types and utilities.
       - [`<promise-iter>.map(..)` / `<promise-iter>.filter(..)` / `<promise-iter>.reduce(..)`](#promise-itermap--promise-iterfilter--promise-iterreduce)
       - [`<promise-iter>.flat(..)`](#promise-iterflat)
       - [`<promise-iter>.reverse()`](#promise-iterreverse)
+      - [`<promise-iter>.concat(..)`](#promise-iterconcat)
+      - [`<promise-iter>.push(..)` / `<promise-iter>.unshift(..)`](#promise-iterpush--promise-iterunshift)
       - [`<promise-iter>.then(..)` / `<promise-iter>.catch(..)` / `<promise-iter>.finally(..)`](#promise-iterthen--promise-itercatch--promise-iterfinally)
       - [Advanced handler](#advanced-handler)
     - [Promise proxies](#promise-proxies)
@@ -1619,6 +1621,31 @@ but rather a _reversed copy_ will be created.
 This is similar to [`<array>.reverse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) see it for more info.
 
 
+#### `<promise-iter>.concat(..)`
+
+```bnf
+<promise-iter>.concat(<other>)
+    -> <promise-iter>
+```
+
+This is similar to [`<array>.concat(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) see it for more info.
+
+
+#### `<promise-iter>.push(..)` / `<promise-iter>.unshift(..)`
+
+```bnf
+<promise-iter>.push(<elem>)
+    -> <promise-iter>
+
+<promise-iter>.unshift(<elem>)
+    -> <promise-iter>
+```
+
+These are similar to [`<array>.push(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) 
+and [`<array>.unshift(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) 
+see them for more info.
+
+
 #### `<promise-iter>.then(..)` / `<promise-iter>.catch(..)` / `<promise-iter>.finally(..)`
 
 An extension to