Improce docs

Author: gmazzap

README.md

@@ -17,7 +17,7 @@ It provides **two set of helpers**:
 
   - PHP 5.6+
   - [Composer](https://getcomposer.org/) to install
- 
+
 Via Composer following packages are required:
 
   - [mockery/mockery](https://packagist.org/packages/mockery/mockery) version 1 (BSD-3-Clause)
@@ -42,4 +42,5 @@ Brain Monkey is hosted on GitHub. Feel free to open issues there for suggestions
 
 I'm Giuseppe, I deal with PHP since 2005. For questions, rants or chat ping me on Twitter ([@gmazzap](https://twitter.com/gmazzap)) 
 or on ["The Loop"](http://chat.stackexchange.com/rooms/6/the-loop) (Stack Exchange) chat.
-Well, it's possible I'll ignore rants.
+
+Well, it's possible I'll ignore rants.

docs/functions-expect.md

@@ -5,73 +5,74 @@ title: "Testing functions with expect()"
 -->
 # Testing functions with expect()
 
-Often, in tests, what we need is not only to enforce a function returned value (what `when()` allows to do), but
-to test function behavior based on **expectations**.
+Often, in tests, what we need is not only to enforce a function returned value (what `Functions\when()` allows to do), but to test function behavior based on **expectations**.
 
-Mockery has a very powerful, and human readable Domain Specific Language (DSL) that allows to set expectations
-on how object methods should behave, e.g. validate arguments they should receive, how many times they are called, and so on.
+Mockery has a very powerful, and human readable Domain Specific Language (DSL) that allows to set expectations on how object methods should behave, e.g. validate arguments they should receive, how many times they are called, and so on.
 
-Brain Monkey brings that power to function testing. The entry-point is the `Functions::expect()` method.
+Brain Monkey brings that power to function testing. The entry-point is the `Functions\expect()` function.
 
 It receives a function name and returns a Mockery expectation object with all its power.
 
 Below there are just several examples, for the full story about Mockery expectations see its [documentation](http://docs.mockery.io/en/latest/reference/index.html).
 
-Only note that in functions testing the `shouldReceive` Mockery method makes **no sense**, don't use it (an exception will be thrown if you do that).
+Only note that in functions testing the `shouldReceive` Mockery method makes **no sense**, so don't use it (an exception will be thrown if you do that).
+
+
 
 
 ## Expectations on times a function is called
 
 ```php
-Functions::expect('paganini')->once();
+Functions\expect('paganini')->once();
 
-Functions::expect('tween')->twice();
+Functions\expect('tween')->twice();
 
-Functions::expect('who_knows')->zeroOrMoreTimes();
+Functions\expect('who_knows')->zeroOrMoreTimes();
 
-Functions::expect('i_should_run')->atLeast()->once();
+Functions\expect('i_should_run')->atLeast()->once();
 
-Functions::expect('i_have_a_max')->atMost()->twice();
+Functions\expect('i_have_a_max')->atMost()->twice();
 
-Functions::expect('poor_me')->never();
+Functions\expect('poor_me')->never();
 
-Functions::expect('pretty_precise')->times(3);
+Functions\expect('pretty_precise')->times(3);
 
-Functions::expect('i_have_max_and_min')->between(2, 4);
+Functions\expect('i_have_max_and_min')->between(2, 4);
 ```
 
 There is no need to explain how it works: Mockery DSL reads like plain English.
 
 Of course, expectation on the times a function should run can be combined with arguments expectation.
 
 
+
 ## Expectations on received arguments
 
 Below a few examples, for the full story see [Mockery docs](http://docs.mockery.io/en/latest/reference/argument_validation.html).
 
 ```php
 // allow anything
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->once()
   ->withAnyArgs();
 
 // allow nothing
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->once()
   ->withNoArgs();
 
 // validate specific arguments
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->once()
   ->with('arg_1', 'arg2');
 
 // validate specific argument types
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->times(3)
   ->with(Mockery::type('resource'), Mockery::type('int'));
 
 // validate anything in specific places
-Functions::expect('function_name')
+Functions\expect('function_name')
     ->zeroOrMoreTimes()
     ->with(Mockery::any());
 
@@ -81,44 +82,46 @@ Functions::expect('function_name')
     ->with(Mockery::anyOf('a', 'b', 'c'));
 
 // regex validation
-Functions::expect('function_name')
+Functions\expect('function_name')
     ->once()
     ->with('/^foo/');
 
 // excluding specific values
-Functions::expect('function_name')
+Functions\expect('function_name')
     ->once()
     ->with(Mockery::not(2, 3));
 
 // dealing with array arguments
-Functions::expect('function_name')
+Functions\expect('function_name')
     ->once()
     ->with(Mockery::hasKey('foo'), Mockery::contains('bar', 'baz'));
 ```
 
+
+
 ## Forcing behavior
 
 Excluding `shouldReceive`, all the Mockery expectation methods can be used with Brain Monkey, including
 `andReturn` or `andReturnUsing` used to enforce a function to return specific values during tests.
 
-In fact, `Functions::when()` do same thing for simple cases when no expectations are required.
+In fact, `Functions\when()` do same thing for simple cases when no expectations are required.
 
 Again, just a few examples:
 
 ```php
 // return a specific value
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->once()
   ->with('foo', 'bar')
   ->andReturn('Baz!');
 
 // return values in order
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->twice()
   ->andReturn('First time I run', 'Second time I run');
 
 // return values in order, alternative
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->twice()
   ->andReturnValues(['First time I run', 'Second time I run']);
 
@@ -128,15 +131,15 @@ Functions::expect('function_name')
   ->andReturnNull();
 
 // use a callback for returning a value
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->atLeast()
   ->once()
   ->andReturnUsing(function() {
       return 'I am an alias!';
   });
 
 // makes function throws an Exception (e.g. to test try statements)
-Functions::expect('function_name')
+Functions\expect('function_name')
   ->once()
   ->andThrow('RuntimeException'); // Both exception names and object are supported
 ```

docs/functions-setup.md

@@ -5,36 +5,41 @@ title: "Setup Brain Monkey"
 -->
 # Testing PHP Functions: Setup Brain Monkey
 
+
+
 ## Testing framework agnostic
 
 Brain Monkey can be used with any testing framework.
+
 Examples in this page will use PHPUnit, but the concepts are applicable at any testing framework.
 
+
+
 ## Warning
 
-Brain Monkey uses [Patchwork](http://antecedent.github.io/patchwork/) to redefine functions and so inherits from it some gotchas:
+Brain Monkey uses [Patchwork](http://antecedent.github.io/patchwork/) to redefine functions.
+
+Brain Monkey 2.* requires Patchwork 2 which allows to re-define both userland and core functions,
+with some [limitations](http://patchwork2.org/limitations/).
 
- - only **userland** (custom) functions can be redefined, PHP core functions can't.
+The main limitations that affects Brain Monkey are (from Patchwork website):
 
- - only functions defined **after** Patchwork as been loaded can be redefined. Brain Monkey loads Patchwork when you call `Monkey::setUp()` (see below).
+- _Patchwork will fail on every attempt to redefine an internal function that is missing from the redefinable-internals array of your `patchwork.json`._
+- _Make sure that Patchwork is imported as early as possible, since any files imported earlier, including the one from which the importing takes place, will be missed by Patchwork's code preprocessor._
 
-   That happen at the start of any test. If functions you want to test are defined earlier (e.g. via Composer "file" autoload directive) you need to "manually" load Patchwork earlier
-   (you'll need to require `Patchwork.php` file, see Patchwork docs).
 
-   Note that this is something you **don't** have to worry about if functions you want to test are not defined at all during tests.
 
 
 ## Setup tests
 
 After Brain Monkey is part of the project (see *Getting Started / Installation*), to be able to use its features
-you need to **require vendor autoload file** before running tests (e.g. PHPUnit users will probably require it in their bootstrap file).
+two simple steps are needed before being able to use Brain Monkey in tests:
+
+1. be sure to require Composer autoload file _before_ running tests (e.g. PHPUnit users will probably require it in their bootstrap file).
+2. call the function `Brain\Monkey\tearDown()` after any test
 
-After that you need to call a method *before* any test, and another *after* any test.
 
-These two methods are:
 
- - `Brain\Monkey::setUp()` has to be run before any test
- - `Brain\Monkey::tearDown()` has to be run after any test
 
 ### PHPUnit example
 
@@ -47,15 +52,9 @@ use Brain\Monkey;
 class MyTestCase extends PHPUnit_Framework_TestCase
 {
 
-    protected function setUp()
-    {
-        parent::setUp();
-        Monkey::setUp();
-    }
-
     protected function tearDown()
     {
-        Monkey::tearDown();
+        Monkey\tearDown();
         parent::tearDown();
     }
 }
@@ -65,30 +64,33 @@ After that for all test classes can extend this class instead of directly extend
 
 That's all. Again, I used PHPUnit for the example, but any testing framework can be used.
 
-Now you are ready to start testing functions.
+For function mocking and testing there are two entry-point functions:
+
+-  **`Functions\when()`** 
+- **`Functions\expect()`**
+
+See dedicated documentation pages.
 
-For the scope there are two entry-point methods of the `Functions` class: **`when()`** and **`expect()`**.
-See dedicated doc pages.
 
 
 ## Namespaced functions
 
 All the code examples in this documentation make use of functions in global namespace.
-However, note that namespaced functions are supported as well, just be sure to pass the fully qualified name of the function
-to `Functions` methods:
+
+However, note that namespaced functions are supported as well, just be sure to pass the fully qualified name of the functions:
 
 ```php
-Functions::expect('a_global_function');
+Functions\expect('a_global_function');
 
-Functions::expect('My\\App\\awesome_function()');
+Functions\expect('My\\App\\awesome_function');
 ```
 
 
+
 ## Note for WordPressers
 
 Anything said in this page is fine for WordPress functions too, they are PHP functions, after all.
 
 However, Brain Monkey has specific features for WordPress, and there is a way to setup tests for **all** Brain Monkey features (WordPress-specific and not).
 
-If you want to use Brain Monkey to test code wrote for WordPress, it is preferable to use the setup explained in the *"WordPress / Setup"* section
-that *includes* the setup needed to use Brain Monkey tools for functions.
+**If you want to use Brain Monkey to test code wrote for WordPress, it is preferable to use the setup explained in the *"WordPress / Setup"* section that *includes* the setup needed to use Brain Monkey tools for functions.**