From 2ac61f7af7e069488af67eb3a3cb5655772e7b79 Mon Sep 17 00:00:00 2001
From: Charlike Mike Reagent <olsten.larck@gmail.com>
Date: Tue, 14 Nov 2017 16:31:22 +0200
Subject: [PATCH] fix(readme): generate readme

Signed-off-by: Charlike Mike Reagent <olsten.larck@gmail.com>
---
 README.md    | 77 +++++++++++++++++++++++++++++++++++++++++++++++
 src/index.js | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 161 insertions(+)

diff --git a/README.md b/README.md
index 640cb77..95b9ef7 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,8 @@ You may also read the [Contributing Guide](./CONTRIBUTING.md). There, beside _"H
 ## Table of Contents
 - [Install](#install)
 - [API](#api)
+  * [.exec](#exec)
+  * [.shell](#shell)
 - [Related Projects](#related-projects)
 - [Contributing](#contributing)
 - [Contributors](#contributors)
@@ -69,6 +71,81 @@ See available bundles at [`https://unpkg.com/execa-pro/dist/browser/`](https://u
 ## API
 Review carefully the provided examples and the working [tests](./test).
 
+### [.exec](src/index.js#L46)
+> Same as [execa][]'s main export [here](https://github.com/sindresorhus/execa#execafile-arguments-options) As state there, think of it as mix of `child_process`'s `.execFile` and `.spawn`. It is pretty similar to the `.shell` method too, but only visually because it does not uses the system's shell.
+
+> It also can accept array of multiple strings of commands that will be
+executed in series.
+
+**Params**
+
+* `cmds` **{string|Array}**: a commands to execute, if array of strings executes them serially    
+* `opts` **{Object}**: directly passed to [execa][] and so to `child_process`    
+* `returns` **{Promise}**: resolved or rejected promises  
+
+**Example**
+
+```js
+const { exec } = require('execa-pro')
+
+async function init () {
+  await exec('echo "hello world"', { stdio: 'inherit' })
+
+  // executes in series
+  await exec([
+    'prettier-eslint --write foobar.js',
+    'eslint --format codeframe foobar.js --fix'
+  ], { stdio: 'inherit', preferLocal: true })
+}
+
+init()
+```
+
+### [.shell](src/index.js#L99)
+> Same as [execa][]'s `.shell` method, but also can accept an array of multiple commands that will be executed in the system's shell, [see its docs](https://github.com/sindresorhus/execa#execashellcommand-options) for more info.
+
+**Params**
+
+* `cmds` **{string|Array}**: a commands to execute, if array of strings executes them serially    
+* `opts` **{Object}**: directly passed to `execa.shell` method.    
+* `returns` **{Promise}**: resolved or rejected promises  
+
+**Example**
+
+```js
+const { shell } = require('execa-pro')
+
+async function init () {
+  // executes in series
+  await shell([
+    'echo unicorns',
+    'echo dragons'
+  ], { stdio: 'inherit' })
+
+  // exits with code 3
+  try {
+    await shell([
+      'exit 3',
+      'echo nah'
+    ])
+  } catch (er) {
+    console.error(er)
+    // => {
+    //  message: 'Command failed: /bin/sh -c exit 3'
+    //  killed: false,
+    //  code: 3,
+    //  signal: null,
+    //  cmd: '/bin/sh -c exit 3',
+    //  stdout: '',
+    //  stderr: '',
+    //  timedOut: false
+    // }
+  }
+}
+
+init()
+```
+
 **[back to top](#thetop)**
 
 ## Related Projects
diff --git a/src/index.js b/src/index.js
index 893612d..a2de72e 100644
--- a/src/index.js
+++ b/src/index.js
@@ -8,10 +8,94 @@ const pMap = require('p-map-series')
 
 module.exports = { exec, shell }
 
+/**
+ * > Same as [execa][]'s main export
+ * [here](https://github.com/sindresorhus/execa#execafile-arguments-options)
+ * As state there, think of it as mix of `child_process`'s `.execFile` and `.spawn`.
+ * It is pretty similar to the `.shell` method too, but only visually because
+ * it does not uses the system's shell.
+ *
+ * > It also can accept array of multiple strings of commands that will be
+ * executed in series.
+ *
+ * **Example**
+ *
+ * ```js
+ * const { exec } = require('execa-pro')
+ *
+ * async function init () {
+ *   await exec('echo "hello world"', { stdio: 'inherit' })
+ *
+ *   // executes in series
+ *   await exec([
+ *     'prettier-eslint --write foobar.js',
+ *     'eslint --format codeframe foobar.js --fix'
+ *   ], { stdio: 'inherit', preferLocal: true })
+ * }
+ *
+ * init()
+ * ```
+ *
+ * @name   .exec
+ * @param  {string|Array} `cmds` a commands to execute, if array of strings executes them serially
+ * @param  {Object} `opts` directly passed to [execa][] and so to `child_process`
+ * @return {Promise} resolved or rejected promises
+ * @api public
+ */
+
 function exec (cmds, opts) {
   return factory('exec')(cmds, opts)
 }
 
+/**
+ * > Same as [execa][]'s `.shell` method, but also can accept an array of multiple
+ * commands that will be executed in the system's shell,
+ * [see its docs](https://github.com/sindresorhus/execa#execashellcommand-options)
+ * for more info.
+ *
+ * **Example**
+ *
+ * ```js
+ * const { shell } = require('execa-pro')
+ *
+ * async function init () {
+ *   // executes in series
+ *   await shell([
+ *     'echo unicorns',
+ *     'echo dragons'
+ *   ], { stdio: 'inherit' })
+ *
+ *   // exits with code 3
+ *   try {
+ *     await shell([
+ *       'exit 3',
+ *       'echo nah'
+ *     ])
+ *   } catch (er) {
+ *     console.error(er)
+ *     // => {
+ *     //  message: 'Command failed: /bin/sh -c exit 3'
+ *     //  killed: false,
+ *     //  code: 3,
+ *     //  signal: null,
+ *     //  cmd: '/bin/sh -c exit 3',
+ *     //  stdout: '',
+ *     //  stderr: '',
+ *     //  timedOut: false
+ *     // }
+ *   }
+ * }
+ *
+ * init()
+ * ```
+ *
+ * @name   .shell
+ * @param  {string|Array} `cmds` a commands to execute, if array of strings executes them serially
+ * @param  {Object} `opts` directly passed to `execa.shell` method.
+ * @return {Promise} resolved or rejected promises
+ * @api public
+ */
+
 function shell (cmds, opts) {
   return factory('shell')(cmds, opts)
 }