update docs

README.md

@@ -31,10 +31,26 @@ const letta = require('letta')
 const letta = require('letta')
 
 letta((foo, bar, baz) => {
-  console.log(foo, bar, baz) //=> 'foo, bar, baz'
+  console.log(foo, bar, baz) // => 'foo, bar, baz'
   return foo
 }, 'foo', 'bar', 'baz')
-.then(console.log) //=> 'foo'
+.then(console.log) // => 'foo'
+```
+
+### [.wrap](./index.js#L75)
+> Convert a generator into a regular function that returns a `Promise`.
+
+**Example**
+
+```js
+const letta = require('letta')
+const fn = letta.wrap(function * (val) {
+  return yield Promise.resolve(val)
+})
+
+fn(123).then(function (val) {
+  console.log(val) // => 123
+}, console.error)
 ```
 
 ### Callbacks
@@ -49,13 +65,13 @@ const letta = require('letta')
 letta(fs.readFile, 'package.json', 'utf8')
 .then(JSON.parse)
 .then(data => {
-  console.log(data.name) //=> 'letta'
+  console.log(data.name) // => 'letta'
 }, console.error)
 
 // callback `fs.stat` function
 letta(fs.stat, 'package.json')
 .then(stats => {
-  console.log(stats.isFile()) //=> true
+  console.log(stats.isFile()) // => true
 }, console.error)
 ```
 
@@ -73,7 +89,7 @@ letta(function * (fp) {
 }, 'package.json')
 .then(JSON.parse)
 .then(data => {
-  console.log(data.name) //=> 'letta'
+  console.log(data.name) // => 'letta'
 }, console.error)
 ```
 
@@ -85,7 +101,7 @@ const letta = require('letta')
 
 letta(JSON.stringify, {foo: 'bar'})
 .then(data => {
-  console.log(data) //=> {"foo":"bar"}
+  console.log(data) // => {"foo":"bar"}
 }, console.error)
 
 // result with identation
@@ -109,13 +125,13 @@ const letta = require('letta')
 // sync function
 letta(fs.statSync, 'package.json')
 .then(stats => {
-  console.log(stats.isFile()) //=> true
+  console.log(stats.isFile()) // => true
 }, console.error)
 
 // correct handling of optional arguments
 letta(fs.readFileSync, 'package.json')
 .then(buf => {
-  console.log(Buffer.isBuffer(buf)) //=> true
+  console.log(Buffer.isBuffer(buf)) // => true
 }, console.error)
 ```
 
@@ -130,7 +146,7 @@ const letta = require('letta')
 
 letta(fs.readFile, 'foobar.json')
 .then(console.log, err => {
-  console.error(err.code) //=> 'ENOENT'
+  console.error(err.code) // => 'ENOENT'
 })
 
 // handles ReferenceError,
@@ -139,7 +155,7 @@ letta(function () {
   foo
   return true
 })
-.catch(console.error) //=> 'ReferenceError: foo is not defined'
+.catch(console.error) // => 'ReferenceError: foo is not defined'
 ```
 
 ### Errors
@@ -154,7 +170,7 @@ letta(function () {
   return new Error('foo err bar')
 })
 .catch(err => {
-  console.log(err.message) //=> 'foo err bar'
+  console.log(err.message) // => 'foo err bar'
 })
 ```
 
@@ -170,7 +186,7 @@ letta(function (foo) {
   return foo
 })
 .then(console.log, err => {
-  console.log(err.message) //=> 'foo err bar'
+  console.log(err.message) // => 'foo err bar'
 })
 ```
 
@@ -193,9 +209,64 @@ letta((str, num, obj, fn) => {
   assert.strictEqual(typeof fn, 'function')
   return true
 }, 'foo', 123, {a: 'b'}, function () {})
-.then(console.log) //=> true
+.then(console.log) // => true
+```
+
+## Yieldables
+> The `yieldable` objects currently supported are:
+
+- promises
+- thunks (functions)
+- array (parallel execution)
+- objects (parallel execution)
+- generators (delegation)
+- generator functions (delegation)
+
+Nested `yieldable` objects are supported, meaning you can nest
+promises within objects within arrays, and so on!
+
+### Promises
+[Read more on promises!](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+
+### Thunks
+Thunks are functions that only have a single argument, a callback.
+Thunk support only remains for backwards compatibility.
+
+### Arrays
+`yield`ing an array will resolve all the `yieldables` in parallel.
+
+```js
+letta(function * () {
+  var res = yield [
+    Promise.resolve(1),
+    Promise.resolve(2),
+    Promise.resolve(3),
+  ]
+  console.log(res) // => [1, 2, 3]
+})
+.catch(console.error)
+```
+
+### Objects
+Just like arrays, objects resolve all `yieldable`s in parallel.
+
+```js
+letta(function* () {
+  var res = yield {
+    1: Promise.resolve(1),
+    2: Promise.resolve(2),
+  }
+  console.log(res) // => { 1: 1, 2: 2 }
+})
+.catch(console.error)
 ```
 
+### Generators and Generator Functions
+Any generator or generator function you can pass into `letta`
+can be yielded as well. This should generally be avoided
+as we should be moving towards spec-compliant `Promise`s instead.
+
+
 ## Contributing
 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/hybridables/letta/issues/new).  
 But before doing anything, please read the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines.

index.js

@@ -12,7 +12,7 @@ var isGenFn = require('is-es6-generator-function')
 var getPromise = require('native-or-another')
 
 /**
- * Control flow now and then.
+ * > Control flow now and then.
  *
  * **Example**
  *
@@ -51,7 +51,27 @@ var letta = module.exports = function letta (fn, args) {
   })
 }
 
-// just for 100% `co@4` comaptibility
+/**
+ * > Convert a generator into a regular function that returns a `Promise`.
+ *
+ * **Example**
+ *
+ * ```js
+ * const letta = require('letta')
+ * const fn = letta.wrap(function * (val) {
+ *   return yield Promise.resolve(val)
+ * })
+ *
+ * fn(123).then(function (val) {
+ *   console.log(val) // => 123
+ * }, console.error)
+ * ```
+ *
+ * @name   .wrap
+ * @param  {Function} `<fn>`
+ * @return {Function}
+ * @api public
+ */
 letta.wrap = function lettaWrap (val) {
   function createPromise () {
     var args = sliced(arguments)