From 15756aa0c88591c10108e740ad3096a3af966242 Mon Sep 17 00:00:00 2001 From: Gennadiy Civil Date: Thu, 18 Jul 2019 11:39:49 -0400 Subject: [PATCH] Manual docs tweaks still in preparation for including docs with code pushes --- googlemock/docs/cheat_sheet.md | 156 ++++++++++++++++++++------------- googlemock/docs/cook_book.md | 4 +- googlemock/docs/for_dummies.md | 2 +- googletest/docs/faq.md | 2 +- 4 files changed, 98 insertions(+), 66 deletions(-) diff --git a/googlemock/docs/cheat_sheet.md b/googlemock/docs/cheat_sheet.md index 06190d16..e839fa9d 100644 --- a/googlemock/docs/cheat_sheet.md +++ b/googlemock/docs/cheat_sheet.md @@ -215,7 +215,7 @@ and the default action will be taken each time. ### Matchers {#MatcherList} - + A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or `EXPECT_CALL()`, or use it to validate a value directly: @@ -340,67 +340,99 @@ or simply `expected_container` to match a container exactly. If you want to write the elements in-line, match them more flexibly, or get more informative messages, you can use: -| Matcher | Description | -| :----------------------------------- | :----------------------------------- | -| `ContainerEq(container)` | The same as `Eq(container)` except | -: : that the failure message also : -: : includes which elements are in one : -: : container but not the other. : -| `Contains(e)` | `argument` contains an element that | -: : matches `e`, which can be either a : -: : value or a matcher. : -| `Each(e)` | `argument` is a container where | -: : _every_ element matches `e`, which : -: : can be either a value or a matcher. : -| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, | -: : where the i-th element matches `ei`, : -: : which can be a value or a matcher. 0 : -: : to 10 arguments are allowed. : -| `ElementsAreArray({ e0, e1, ..., en | The same as `ElementsAre()` except | -: })`, `ElementsAreArray(array)`, or : that the expected element : -: `ElementsAreArray(array, count)` : values/matchers come from an : -: : initializer list, STL-style : -: : container, or C-style array. : -| `IsEmpty()` | `argument` is an empty container | -: : (`container.empty()`). : -| `Pointwise(m, container)` | `argument` contains the same number | -: : of elements as in `container`, and : -: : for all i, (the i-th element in : -: : `argument`, the i-th element in : -: : `container`) match `m`, which is a : -: : matcher on 2-tuples. E.g. : -: : `Pointwise(Le(), upper_bounds)` : -: : verifies that each element in : -: : `argument` doesn't exceed the : -: : corresponding element in : -: : `upper_bounds`. See more detail : -: : below. : -| `SizeIs(m)` | `argument` is a container whose size | -: : matches `m`. E.g. `SizeIs(2)` or : -: : `SizeIs(Lt(2))`. : -| `UnorderedElementsAre(e0, e1, ..., | `argument` has `n + 1` elements, and | -: en)` : under some permutation each element : -: : matches an `ei` (for a different : -: : `i`), which can be a value or a : -: : matcher. 0 to 10 arguments are : -: : allowed. : -| `UnorderedElementsAreArray({ e0, e1, | The same as `UnorderedElementsAre()` | -: ..., en })`, : except that the expected element : -: `UnorderedElementsAreArray(array)`, : values/matchers come from an : -: or `UnorderedElementsAreArray(array, : initializer list, STL-style : -: count)` : container, or C-style array. : -| `WhenSorted(m)` | When `argument` is sorted using the | -: : `<` operator, it matches container : -: : matcher `m`. E.g. : -: : `WhenSorted(ElementsAre(1, 2, 3))` : -: : verifies that `argument` contains : -: : elements `1`, `2`, and `3`, ignoring : -: : order. : -| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, except | -: : that the given comparator instead of : -: : `<` is used to sort `argument`. E.g. : -: : `WhenSortedBy(std\:\:greater(), : -: : ElementsAre(3, 2, 1))`. : +| Matcher | Description | +| :---------------------------------------- | :------------------------------- | +| `BeginEndDistanceIs(m)` | `argument` is a container whose | +: : `begin()` and `end()` iterators : +: : are separated by a number of : +: : increments matching `m`. E.g. : +: : `BeginEndDistanceIs(2)` or : +: : `BeginEndDistanceIs(Lt(2))`. For : +: : containers that define a : +: : `size()` method, `SizeIs(m)` may : +: : be more efficient. : +| `ContainerEq(container)` | The same as `Eq(container)` | +: : except that the failure message : +: : also includes which elements are : +: : in one container but not the : +: : other. : +| `Contains(e)` | `argument` contains an element | +: : that matches `e`, which can be : +: : either a value or a matcher. : +| `Each(e)` | `argument` is a container where | +: : *every* element matches `e`, : +: : which can be either a value or a : +: : matcher. : +| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, | +: : where the *i*-th element matches : +: : `ei`, which can be a value or a : +: : matcher. : +| `ElementsAreArray({e0, e1, ..., en})`, | The same as `ElementsAre()` | +: `ElementsAreArray(a_container)`, : except that the expected element : +: `ElementsAreArray(begin, end)`, : values/matchers come from an : +: `ElementsAreArray(array)`, or : initializer list, STL-style : +: `ElementsAreArray(array, count)` : container, iterator range, or : +: : C-style array. : +| `IsEmpty()` | `argument` is an empty container | +: : (`container.empty()`). : +| `IsFalse()` | `argument` evaluates to `false` | +: : in a Boolean context. : +| `IsSubsetOf({e0, e1, ..., en})`, | `argument` matches | +: `IsSubsetOf(a_container)`, : `UnorderedElementsAre(x0, x1, : +: `IsSubsetOf(begin, end)`, : ..., xk)` for some subset `{x0, : +: `IsSubsetOf(array)`, or : x1, ..., xk}` of the expected : +: `IsSubsetOf(array, count)` : matchers. : +| `IsSupersetOf({e0, e1, ..., en})`, | Some subset of `argument` | +: `IsSupersetOf(a_container)`, : matches : +: `IsSupersetOf(begin, end)`, : `UnorderedElementsAre(`expected : +: `IsSupersetOf(array)`, or : matchers`)`. : +: `IsSupersetOf(array, count)` : : +| `IsTrue()` | `argument` evaluates to `true` | +: : in a Boolean context. : +| `Pointwise(m, container)`, `Pointwise(m, | `argument` contains the same | +: {e0, e1, ..., en})` : number of elements as in : +: : `container`, and for all i, (the : +: : i-th element in `argument`, the : +: : i-th element in `container`) : +: : match `m`, which is a matcher on : +: : 2-tuples. E.g. `Pointwise(Le(), : +: : upper_bounds)` verifies that : +: : each element in `argument` : +: : doesn't exceed the corresponding : +: : element in `upper_bounds`. See : +: : more detail below. : +| `SizeIs(m)` | `argument` is a container whose | +: : size matches `m`. E.g. : +: : `SizeIs(2)` or `SizeIs(Lt(2))`. : +| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, | +: : and under *some* permutation of : +: : the elements, each element : +: : matches an `ei` (for a different : +: : `i`), which can be a value or a : +: : matcher. : +| `UnorderedElementsAreArray({e0, e1, ..., | The same as | +: en})`, : `UnorderedElementsAre()` except : +: `UnorderedElementsAreArray(a_container)`, : that the expected element : +: `UnorderedElementsAreArray(begin, end)`, : values/matchers come from an : +: `UnorderedElementsAreArray(array)`, or : initializer list, STL-style : +: `UnorderedElementsAreArray(array, count)` : container, iterator range, or : +: : C-style array. : +| `UnorderedPointwise(m, container)`, | Like `Pointwise(m, container)`, | +: `UnorderedPointwise(m, {e0, e1, ..., : but ignores the order of : +: en})` : elements. : +| `WhenSorted(m)` | When `argument` is sorted using | +: : the `<` operator, it matches : +: : container matcher `m`. E.g. : +: : `WhenSorted(ElementsAre(1, 2, : +: : 3))` verifies that `argument` : +: : contains elements 1, 2, and 3, : +: : ignoring order. : +| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, | +: : except that the given comparator : +: : instead of `<` is used to sort : +: : `argument`. E.g. : +: : `WhenSortedBy(std\:\:greater(), : +: : ElementsAre(3, 2, 1))`. : **Notes:** diff --git a/googlemock/docs/cook_book.md b/googlemock/docs/cook_book.md index 10b6d85b..a858cd1f 100644 --- a/googlemock/docs/cook_book.md +++ b/googlemock/docs/cook_book.md @@ -154,7 +154,7 @@ class MockStack : public StackInterface { #### Mocking Non-virtual Methods {#MockingNonVirtualMethods} gMock can mock non-virtual functions to be used in Hi-perf dependency -injection.. +injection.. In this case, instead of sharing a common base class with the real class, your mock class will be *unrelated* to the real class, but contain methods with the @@ -1455,7 +1455,7 @@ mock object and gMock. #### Knowing When to Expect {#UseOnCall} - + **`ON_CALL`** is likely the *single most under-utilized construct* in gMock. diff --git a/googlemock/docs/for_dummies.md b/googlemock/docs/for_dummies.md index 198da467..5433e8b3 100644 --- a/googlemock/docs/for_dummies.md +++ b/googlemock/docs/for_dummies.md @@ -499,7 +499,7 @@ always return 100 as `n++` is only evaluated once. Similarly, `Return(new Foo)` will create a new `Foo` object when the `EXPECT_CALL()` is executed, and will return the same pointer every time. If you want the side effect to happen every time, you need to define a custom action, which we'll teach in the -[cook book](http://). +[cook book](http://). Time for another quiz! What do you think the following means? diff --git a/googletest/docs/faq.md b/googletest/docs/faq.md index a22f1b90..0e9cfeeb 100644 --- a/googletest/docs/faq.md +++ b/googletest/docs/faq.md @@ -332,7 +332,7 @@ You may still want to use `SetUp()/TearDown()` in the following cases: * In the body of a constructor (or destructor), it's not possible to use the `ASSERT_xx` macros. Therefore, if the set-up operation could cause a fatal test failure that should prevent the test from running, it's necessary to - use `abort` and abort the whole test executable, + use `abort` and abort the whole test executable, or to use `SetUp()` instead of a constructor. * If the tear-down operation could throw an exception, you must use `TearDown()` as opposed to the destructor, as throwing in a destructor leads