Manual docs tweaks still in preparation for including docs with code pushes

4 files changed, 131 insertions, 29 deletions

diff --git a/googlemock/docs/cheat_sheet.md b/googlemock/docs/cheat_sheet.md
index e839fa9d..6441a7a8 100644
--- a/googlemock/docs/cheat_sheet.md
+++ b/googlemock/docs/cheat_sheet.md
@@ -2,6 +2,8 @@
 
 <!-- GOOGLETEST_CM0019 DO NOT DELETE -->
 
+<!-- GOOGLETEST_CM0033 DO NOT DELETE -->
+
 ### Defining a Mock Class
 
 #### Mocking a Normal Class {#MockClass}
@@ -232,7 +234,7 @@ A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
 Built-in matchers (where `argument` is the function argument) are divided into
 several categories:
 
-## Wildcard
+#### Wildcard
 
 Matcher                     | Description
 :-------------------------- | :-----------------------------------------------
@@ -495,6 +497,10 @@ messages, you can use:
 | `WhenDynamicCastTo<T>(m)` | when `argument` is passed through               |
 :                           : `dynamic_cast<T>()`, it matches matcher `m`.    :
 
+<!-- GOOGLETEST_CM0026 DO NOT DELETE -->
+
+<!-- GOOGLETEST_CM0027 DO NOT DELETE -->
+
 #### Multi-argument Matchers {#MultiArgMatchers}
 
 Technically, all matchers match a *single* value. A "multi-argument" matcher is
@@ -525,13 +531,25 @@ reorder them) to participate in the matching:
 
 You can make a matcher from one or more other matchers:
 
-| Matcher                  | Description                                     |
-| :----------------------- | :---------------------------------------------- |
-| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to  |
-:                          : `mn`.                                           :
-| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers |
-:                          : `m1` to `mn`.                                   :
-| `Not(m)`                 | `argument` doesn't match matcher `m`.           |
+| Matcher                          | Description                             |
+| :------------------------------- | :-------------------------------------- |
+| `AllOf(m1, m2, ..., mn)`         | `argument` matches all of the matchers  |
+:                                  : `m1` to `mn`.                           :
+| `AllOfArray({m0, m1, ..., mn})`, | The same as `AllOf()` except that the   |
+: `AllOfArray(a_container)`,       : matchers come from an initializer list, :
+: `AllOfArray(begin, end)`,        : STL-style container, iterator range, or :
+: `AllOfArray(array)`, or          : C-style array.                          :
+: `AllOfArray(array, count)`       :                                         :
+| `AnyOf(m1, m2, ..., mn)`         | `argument` matches at least one of the  |
+:                                  : matchers `m1` to `mn`.                  :
+| `AnyOfArray({m0, m1, ..., mn})`, | The same as `AnyOf()` except that the   |
+: `AnyOfArray(a_container)`,       : matchers come from an initializer list, :
+: `AnyOfArray(begin, end)`,        : STL-style container, iterator range, or :
+: `AnyOfArray(array)`, or          : C-style array.                          :
+: `AnyOfArray(array, count)`       :                                         :
+| `Not(m)`                         | `argument` doesn't match matcher `m`.   |
+
+<!-- GOOGLETEST_CM0028 DO NOT DELETE -->
 
 #### Adapters for Matchers
 
@@ -550,7 +568,7 @@ You can make a matcher from one or more other matchers:
 `AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`,
 which must be a permanent callback.
 
-#### Matchers as Predicates {#MatchersAsPredicatesCheat}
+#### Using Matchers as Predicates {#MatchersAsPredicatesCheat}
 
 | Matcher                       | Description                                 |
 | :---------------------------- | :------------------------------------------ |
@@ -587,20 +605,13 @@ which must be a permanent callback.
 1.  You can use `PrintToString(x)` to convert a value `x` of any type to a
     string.
 
-## Matchers as Test Assertions
-
-Matcher                      | Description
-:--------------------------- | :----------
-`ASSERT_THAT(expression, m)` | Generates a [fatal failure](../../googletest/docs/primer.md#assertions) if the value of `expression` doesn't match matcher `m`.
-`EXPECT_THAT(expression, m)` | Generates a non-fatal failure if the value of `expression` doesn't match matcher `m`.
-
 ### Actions {#ActionList}
 
 **Actions** specify what a mock function should do when invoked.
 
 #### Returning a Value
 
-| Matcher                     | Description                                   |
+|                             |                                               |
 | :-------------------------- | :-------------------------------------------- |
 | `Return()`                  | Return from a `void` mock function.           |
 | `Return(value)`             | Return `value`. If the type of `value` is     |
@@ -619,7 +630,7 @@ Matcher                      | Description
 
 #### Side Effects
 
-| Matcher                            | Description                             |
+|                                    |                                         |
 | :--------------------------------- | :-------------------------------------- |
 | `Assign(&variable, value)`         | Assign `value` to variable.             |
 | `DeleteArg<N>()`                   | Delete the `N`-th (0-based) argument,   |
@@ -652,8 +663,11 @@ Matcher                      | Description
 In the following, by "callable" we mean a free function, `std::function`,
 functor, lambda, or `google3`-style permanent callback.
 
-| Matcher                             | Description                            |
+|                                     |                                        |
 | :---------------------------------- | :------------------------------------- |
+| `f`                                 | Invoke f with the arguments passed to  |
+:                                     : the mock function, where f is a        :
+:                                     : callable (except of google3 callback). :
 | `Invoke(f)`                         | Invoke `f` with the arguments passed   |
 :                                     : to the mock function, where `f` can be :
 :                                     : a global/static function or a functor. :
@@ -708,7 +722,7 @@ InvokeArgument<2>(5, string("Hi"), ByRef(foo))
 calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by
 value, and `foo` by reference.
 
-## Default Action
+#### Default Action
 
 | Matcher       | Description                                            |
 | :------------ | :----------------------------------------------------- |
@@ -718,9 +732,11 @@ value, and `foo` by reference.
 **Note:** due to technical reasons, `DoDefault()` cannot be used inside a
 composite action - trying to do so will result in a run-time error.
 
-## Composite Actions
+<!-- GOOGLETEST_CM0032 DO NOT DELETE -->
 
-| Matcher                        | Description                                 |
+#### Composite Actions
+
+|                                |                                             |
 | :----------------------------- | :------------------------------------------ |
 | `DoAll(a1, a2, ..., an)`       | Do all actions `a1` to `an` and return the  |
 :                                : result of `an` in each invocation. The      :
@@ -734,9 +750,22 @@ composite action - trying to do so will result in a run-time error.
 :                                : it.                                         :
 | `WithoutArgs(a)`               | Perform action `a` without any arguments.   |
 
-## Defining Actions
-
-| Matcher                            | Description                             |
+#### Defining Actions
+
+<table border="1" cellspacing="0" cellpadding="1">
+  <tr>
+    <td>`struct SumAction {` <br>
+        &emsp;`template <typename T>` <br>
+        &emsp;`T operator()(T x, Ty) { return x + y; }` <br>
+        `};`
+    </td>
+    <td> Defines a generic functor that can be used as an action summing its
+    arguments. </td> </tr>
+  <tr>
+  </tr>
+</table>
+
+|                                    |                                         |
 | :--------------------------------- | :-------------------------------------- |
 | `ACTION(Sum) { return arg0 + arg1; | Defines an action `Sum()` to return the |
 : }`                                 : sum of the mock function's argument #0  :
@@ -755,7 +784,7 @@ The `ACTION*` macros cannot be used inside a function or class.
 These are used in `Times()` to specify how many times a mock function will be
 called:
 
-| Matcher           | Description                                            |
+|                   |                                                        |
 | :---------------- | :----------------------------------------------------- |
 | `AnyNumber()`     | The function can be called any number of times.        |
 | `AtLeast(n)`      | The call is expected at least `n` times.               |
diff --git a/googlemock/docs/cook_book.md b/googlemock/docs/cook_book.md
index a858cd1f..17c26459 100644
--- a/googlemock/docs/cook_book.md
+++ b/googlemock/docs/cook_book.md
@@ -1,4 +1,4 @@
-## Googletest Mocking (gMock) Cookbook
+## gMock Cookbook
 
 <!-- GOOGLETEST_CM0012 DO NOT DELETE -->
 
@@ -824,6 +824,7 @@ A frequently used matcher is `_`, which matches anything:
 ```cpp
   EXPECT_CALL(foo, DoThat(_, NotNull()));
 ```
+<!-- GOOGLETEST_CM0022 DO NOT DELETE -->
 
 #### Combining Matchers {#CombiningMatchers}
 
@@ -1138,6 +1139,8 @@ Note that the predicate function / functor doesn't have to return `bool`. It
 works as long as the return value can be used as the condition in in statement
 `if (condition) ...`.
 
+<!-- GOOGLETEST_CM0023 DO NOT DELETE -->
+
 #### Matching Arguments that Are Not Copyable
 
 When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of
@@ -2147,7 +2150,11 @@ own precedence order distinct from the `ON_CALL` precedence order.
 #### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions}
 
 If the built-in actions don't suit you, you can use an existing callable
-(function, `std::function`, method, functor, lambda as an action. ```cpp
+(function, `std::function`, method, functor, lambda as an action.
+
+<!-- GOOGLETEST_CM0024 DO NOT DELETE -->
+
+```cpp
 using ::testing::_; using ::testing::Invoke;
 
 class MockFoo : public Foo {
@@ -3239,6 +3246,8 @@ If you are interested in the mock call trace but not the stack traces, you can
 combine `--gmock_verbose=info` with `--gtest_stack_trace_depth=0` on the test
 command line.
 
+<!-- GOOGLETEST_CM0025 DO NOT DELETE -->
+
 #### Running Tests in Emacs
 
 If you build and run your tests in Emacs using the `M-x google-compile` command
@@ -4175,3 +4184,61 @@ prints the raw bytes in the value and hopes that you the user can figure it out.
 [googletest's advanced guide](../../googletest/docs/advanced.md#teaching-googletest-how-to-print-your-values)
 explains how to extend the printer to do a better job at printing your
 particular type than to dump the bytes.
+
+### Useful Mocks Created Using gMock
+
+<!--#include file="includes/g3_testing_LOGs.md"-->
+<!--#include file="includes/g3_mock_callbacks.md"-->
+
+#### Mock std::function {#MockFunction}
+
+`std::function` is a general function type introduced in C++11. It is a
+preferred way of passing callbacks to new interfaces. Functions are copiable,
+and are not usually passed around by pointer, which makes them tricky to mock.
+But fear not - `MockFunction` can help you with that.
+
+`MockFunction<R(T1, ..., Tn)>` has a mock method `Call()` with the signature:
+
+```cpp
+  R Call(T1, ..., Tn);
+```
+
+It also has a `AsStdFunction()` method, which creates a `std::function` proxy
+forwarding to Call:
+
+```cpp
+  std::function<R(T1, ..., Tn)> AsStdFunction();
+```
+
+To use `MockFunction`, first create `MockFunction` object and set up
+expectations on its `Call` method. Then pass proxy obtained from
+`AsStdFunction()` to the code you are testing. For example:
+
+```cpp
+TEST(FooTest, RunsCallbackWithBarArgument) {
+  // 1. Create a mock object.
+  MockFunction<int(string)> mock_function;
+
+  // 2. Set expectations on Call() method.
+  EXPECT_CALL(mock_function, Call("bar")).WillOnce(Return(1));
+
+  // 3. Exercise code that uses std::function.
+  Foo(mock_function.AsStdFunction());
+  // Foo's signature can be either of:
+  // void Foo(const std::function<int(string)>& fun);
+  // void Foo(std::function<int(string)> fun);
+
+  // 4. All expectations will be verified when mock_function
+  //     goes out of scope and is destroyed.
+}
+```
+
+Remember that function objects created with `AsStdFunction()` are just
+forwarders. If you create multiple of them, they will share the same set of
+expectations.
+
+Although `std::function` supports unlimited number of arguments, `MockFunction`
+implementation is limited to ten. If you ever hit that limit... well, your
+callback has bigger problems than being mockable. :-)
+
+<!-- GOOGLETEST_CM0034 DO NOT DELETE -->
diff --git a/googlemock/docs/for_dummies.md b/googlemock/docs/for_dummies.md
index 5433e8b3..b39a0c8b 100644
--- a/googlemock/docs/for_dummies.md
+++ b/googlemock/docs/for_dummies.md
@@ -1,4 +1,4 @@
-## Googletest Mocking (gMock) for Dummies {#GMockForDummies}
+## gMock for Dummies {#GMockForDummies}
 
 <!-- GOOGLETEST_CM0013 DO NOT DELETE -->
 
@@ -206,6 +206,8 @@ choosing the adaptor interface can make your code easier to write and more
 readable (a net win in the long run), as you can choose `FooAdaptor` to fit your
 specific domain much better than `Foo` does.
 
+<!-- GOOGLETEST_CM0029 DO NOT DELETE -->
+
 ### Using Mocks in Tests
 
 Once you have a mock class, using it is easy. The typical work flow is:
diff --git a/googlemock/docs/gmock_faq.md b/googlemock/docs/gmock_faq.md
index 184c501f..8bc45b18 100644
--- a/googlemock/docs/gmock_faq.md
+++ b/googlemock/docs/gmock_faq.md
@@ -81,6 +81,8 @@ void Bar(int* p);         // Neither p nor *p is const.
 void Bar(const int* p);  // p is not const, but *p is.
 ```
 
+<<!-- GOOGLETEST_CM0030 DO NOT DELETE -->
+
 ### I can't figure out why gMock thinks my expectations are not satisfied. What should I do?
 
 You might want to run your test with `--gmock_verbose=info`. This flag lets
@@ -124,6 +126,8 @@ using ::testing::_;
       .Times(0);
 ```
 
+<!-- GOOGLETEST_CM0031 DO NOT DELETE -->
+
 ### I have a failed test where gMock tells me TWICE that a particular expectation is not satisfied. Isn't this redundant?
 
 When gMock detects a failure, it prints relevant information (the mock function