Update README

- Add documentation for revert feature
- Reformat docs

1 files changed, 60 insertions, 32 deletions

diff --git a/README.md b/README.md
index 077e754..c0571eb 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,11 @@ rewire
 =====
 **Easy dependency injection for node.js unit testing**.
 
+[![Build Status](https://travis-ci.org/jhnns/rewire.svg?branch=master)](http://travis-ci.org/jhnns/rewire)
+[![Dependency Status](https://david-dm.org/jhnns/rewire.svg)](https://david-dm.org/jhnns/rewire)
+[![Coverage Status](https://img.shields.io/coveralls/jhnns/rewire.svg)](https://coveralls.io/r/jhnns/rewire)
+[![Gittip Donate Button](http://img.shields.io/gittip/peerigon.svg)](https://www.gittip.com/peerigon/)
+
 rewire adds a special setter and getter to modules so you can modify their behaviour for better unit testing. You may
 
 - inject mocks for other modules or globals like `process`
@@ -17,28 +22,17 @@ case CoffeeScript needs to be listed in your devDependencies.
 
 If you want to use rewire also on the client-side take a look at [client-side bundlers](https://github.com/jhnns/rewire#client-side-bundlers)
 
-[![Build Status](https://travis-ci.org/jhnns/rewire.svg?branch=master)](http://travis-ci.org/jhnns/rewire)
-[![Dependency Status](https://david-dm.org/jhnns/rewire.svg)](https://david-dm.org/jhnns/rewire)
-[![Coverage Status](https://img.shields.io/coveralls/jhnns/rewire.svg)](https://coveralls.io/r/jhnns/rewire)
-[![Gittip Donate Button](http://img.shields.io/gittip/peerigon.svg)](https://www.gittip.com/peerigon/)
+[![npm status](https://nodei.co/npm/rewire.svg?downloads=true&stars=true)](https://npmjs.org/package/rewire)
 
 <br />
 
-Installation
-------------
-
-`npm install rewire`
-
-<br />
-
-Examples
+Introduction
 --------
 
 Imagine you want to test this module:
 
+`lib/myModule.js`
 ```javascript
-// lib/myModule.js
-
 // With rewire you can change all these variables
 var fs = require("fs"),
     path = "/somewhere/on/the/disk";
@@ -53,9 +47,8 @@ exports.readSomethingFromFileSystem = readSomethingFromFileSystem;
 
 Now within your test module:
 
+`test/myModule.test.js`
 ```javascript
-// test/myModule.test.js
-
 var rewire = require("rewire");
 
 var myModule = rewire("../lib/myModule.js");
@@ -68,7 +61,7 @@ myModule.__set__("path", "/dev/null");
 myModule.__get__("path"); // = '/dev/null'
 ```
 
-This allows you to mock everything in the top-level scope of the module, like the fs-module for example. Just pass the variable name as first parameter and your mock as second.
+This allows you to mock everything in the top-level scope of the module, like the fs module for example. Just pass the variable name as first parameter and your mock as second.
 
 ```javascript
 var fsMock = {
@@ -84,7 +77,7 @@ myModule.readSomethingFromFileSystem(function (err, data) {
 });
 ```
 
-You can also set different variables with one call.
+You can also set multiple variables with one call.
 
 ```javascript
 myModule.__set__({
@@ -106,6 +99,40 @@ myModule.__set__({
 });
 ```
 
+`__set__` returns a function which reverts the changes introduced by this particular `__set__` call
+
+```javascript
+var revert = myModule.__set__("port", 3000);
+
+// port is now 3000
+revert();
+// port is now the previous value 
+```
+
+For your convenience you can also use the `__with__` method which reverts the given changes after it finished.
+
+```javascript
+myModule.__with__({
+    port: 3000
+})(function () {
+    // within this function port is 3000
+});
+// now port is the previous value again
+```
+
+The `__with__` method is also aware of promises. If a thenable is returned all changes stay until the promise has either been resolved or rejected.
+
+```javascript
+myModule.__with__({
+    port: 3000
+})(function () {
+    return new Promise(...);
+}).then(function () {
+    // now port is the previous value again
+});
+// port is still 3000 here because the promise hasn't been resolved yet
+```
+
 ### Caveats
 
 **Difference to require()**<br>
@@ -126,27 +153,28 @@ myModule.__set__("console.log", function () { /* be quiet */ });
 
 <br />
 
-##API
+API
+------
+
+### rewire(filename: String): rewiredModule
+
+Returns a rewired version of the module found at `filename`. Use `rewire()` exactly like `require()`. 
+
+### rewiredModule.&#95;&#95;set&#95;&#95;(name: String, value: *): Function
 
-###rewire(filename): rewiredModule
+Sets the internal variable `name` to the given `value`. Returns a function which can be called to revert the change.
 
-- *filename*: <br/>
-Path to the module that shall be rewired. Use it exactly like require().
+### rewiredModule.&#95;&#95;set&#95;&#95;(obj: Object): Function
 
-###rewiredModule.&#95;&#95;set&#95;&#95;(name, value)
+Takes all enumerable keys of `obj` as variable names and sets the values respectively. Returns a function which can be called to revert the change.
 
-- *name*: <br/>
-Name of the variable to set. The variable should be global or defined with `var` in the top-leve scope of the module.
-- *value*: <br/>
-The value to set.
+### rewiredModule.&#95;&#95;get&#95;&#95;(name: String): *
 
-###rewiredModule.&#95;&#95;set&#95;&#95;(env)
-- *env*: <br/>
-Takes all keys as variable names and sets the values respectively.
+Returns the private variable with the given `name`.
 
-###rewiredModule.&#95;&#95;get&#95;&#95;(name): value
+### rewiredModule.&#95;&#95;with&#95;&#95;(obj: Object): Function&lt;callback: Function>
 
-Returns the private variable.
+Returns a function which - when being called - sets `obj`, executes the given `callback` and reverts `obj`. If `callback` returns a promise, `obj` is only reverted after the promise has been resolved or rejected. For your convenience the returned function passes the received promise through.
 
 <br />