Docs: Fix incorrect sandbox configuration documentation.

[ryan-roemer]

Purpose (TL;DR)

The documentation for sinon.sandbox is incorrect and this PR fixes it. The bug was originally identified in #617.

Background (Problem in detail)

@divmain identified that the sinon.sandbox documentation is wrong in #617 and in a fiddle http://jsfiddle.net/8k0zv6tp/

Here's a concise example:

The documentation says that calling:

var sandbox = sinon.sandbox.create({});

essentially means:

var sandbox = sinon.sandbox.create({
    // ...
    injectInto: null,
    properties: ["spy", "stub", "mock", "clock", "server", "requests"],
    useFakeTimers: true,
    useFakeServer: true
});

This is wrong. In the shell we have:

> var sandbox = sinon.sandbox.create({})
undefined
> sandbox.clock
undefined
> sandbox.server
undefined

What really happens is equivalent to:

var sandbox = sinon.sandbox.create({
    // ...
    injectInto: null,
    properties: ["spy", "stub", "mock"],
    useFakeTimers: false,
    useFakeServer: false
});

The upstream #617 issue was closed with #617 (comment) comment of:

The current documentation shows how to create a sandbox without a config and clearly states that sinon.sandbox.create(config) is an integration feature, that users are likely not to need.

I consider this solved, and am closing this. Feel free to create a PR for the new documentation if you have improvements for this area of the documentation.

As part of the public API, some of our biggest clients use sandbox exclusively for large test suites for better fake management and cleanup, we have a vested interest in making sure the documentation and behavior of sandbox is correct.

So, after the issue was closed I asked "is this a bug? or a documentation bug?" and I haven't received a response. So, I took a hint from the closing comment and making the simplifying assumption it's a documentation bug and here's the requested PR!

Enjoy!

How to verify

The documentation behavior being wrong can be seen with:

$ npm install sinon
$ node
> var sandbox = sinon.sandbox.create({})
undefined

// These **should** be defined.
> sandbox.clock
undefined
> sandbox.server
undefined

// Now, let's do what the PR improved docs say.
> sandbox = sinon.sandbox.create(sinon.defaultConfig)
undefined

// These **should** be defined.
> sandbox.clock
{ now: 0,
  hrNow: 0,
  timeouts: {},
  Date: 
   { [Function: ClockDate]
// ... STUFF ...
> sandbox.server
{ logError: [Function: logError],
  requests: [],
  requestCount: 0,
  queue: [],
  responses: [] }

[coveralls]

Coverage remained the same at 94.957% when pulling 55e437b on FormidableLabs:docs/sandbox-config into c6d01d8 on sinonjs:master.

[mroderick]

I think this is a great contribution, thank you!

Let's get another set of eyes on it, before we merge it

[mantoni]

I agree. Very good contribution. We should get rid of the defaultConfig thingy, in my opinion. The code already has a comment saying that it's exposed for backward compatibility.