Docs: update documentation samples and core rule description

docs/rules/space-in-parens.md

@@ -12,7 +12,7 @@ var x = (1 + 2) * 3;
 
 ## Rule Details
 
-This rule will enforce consistency of spacing directly inside of parentheses, by disallowing or requiring one or more spaces to the right of `(` and to the left of `)`. In either case, `()` will still be allowed.
+This rule will enforce consistent spacing directly inside of parentheses, by disallowing or requiring one or more spaces to the right of `(` and to the left of `)`.
 
 ## Options
 
@@ -66,6 +66,8 @@ foo( 'bar');
 foo('bar' );
 foo('bar');
 
+foo();
+
 var foo = (1 + 2) * 3;
 (function () { return 'bar'; }());
 ```
@@ -75,18 +77,20 @@ Examples of **correct** code for this rule with the `"always"` option:
 ```js
 /*eslint space-in-parens: ["error", "always"]*/
 
-foo();
-
 foo( 'bar' );
 
+foo( );
+
 var foo = ( 1 + 2 ) * 3;
-( function () { return 'bar'; }() );
+( function ( ) { return 'bar'; }( ) );
 ```
 
 ### Exceptions
 
 An object literal may be used as a third array item to specify exceptions, with the key `"exceptions"` and an array as the value. These exceptions work in the context of the first option. That is, if `"always"` is set to enforce spacing, then any "exception" will *disallow* spacing. Conversely, if `"never"` is set to disallow spacing, then any "exception" will *enforce* spacing.
 
+Note that this rule only enforces spacing within parentheses; it does not check spacing within curly or square brackets, but will enforce or disallow spacing of those types of brackets if and only if they are adjacent to an opening or closing parenthesis.
+
 The following exceptions are available: `["{}", "[]", "()", "empty"]`.
 
 Examples of **incorrect** code for this rule with the `"never", { "exceptions": ["{}"] }` option:
@@ -175,8 +179,8 @@ Examples of **correct** code for this rule with the `"never", { "exceptions": ["
 ```js
 /*eslint space-in-parens: ["error", "never", { "exceptions": ["()"] }]*/
 
-foo( (1 + 2) );
-foo( (1 + 2), 1);
+foo( ( 1 + 2 ) );
+foo( ( 1 + 2 ), 1);
 ```
 
 Examples of **incorrect** code for this rule with the `"always", { "exceptions": ["()"] }]` option:
@@ -193,8 +197,8 @@ Examples of **correct** code for this rule with the `"always", { "exceptions": [
 ```js
 /*eslint space-in-parens: ["error", "always", { "exceptions": ["()"] }]*/
 
-foo(( 1 + 2 ));
-foo(( 1 + 2 ), 1 );
+foo((1 + 2));
+foo((1 + 2), 1);
 ```
 
 The `"empty"` exception concerns empty parentheses, and works the same way as the other exceptions, inverting the first option.
@@ -253,6 +257,32 @@ baz( 1, [1,2]);
 foo({bar: 'baz'}, [1, 2]);
 ```
 
+### Allow Empty Method Calls
+
+A common enough requirement is enforce spacing within parentheses when object or array literals are used but still allow empty method calls. Here is one way to achieve that functionality.
+
+Examples of **incorrect** code for this rule with the `"always", { "exceptions": ["empty", "()"] }]` option:
+
+```js
+/*eslint space-in-parens: ["error", "always", { "exceptions": ["empty", "()"] }]*/
+
+bar( x, {bar:'baz'} );
+baz([1,2], 1);
+foo({bar: 'baz'}, [1, 2]);
+foo( )
+```
+
+Examples of **correct** code for this rule with the `"always", { "exceptions": ["empty", "()"] }]` option:
+
+```js
+/*eslint space-in-parens: ["error", "always", { "exceptions": ["empty", "()"] }]*/
+
+bar(x, {bar:'baz'} );
+baz( [1,2], 1);
+foo( {bar: 'baz'}, [1, 2] );
+foo()
+```
+
 ## When Not To Use It
 
 You can turn this rule off if you are not concerned with the consistency of spacing between parentheses.