Merge pull request #3189 from ellert:gtest-help-test-GNU/kFreeBSD

PiperOrigin-RevId: 349349288

7 files changed, 1907 insertions, 0 deletions

diff --git a/googlemock/docs/contribute.md b/googlemock/docs/contribute.md
new file mode 100644
index 00000000..087654c5
--- /dev/null
+++ b/googlemock/docs/contribute.md
@@ -0,0 +1,5 @@
+# How to Contribute
+
+googletest development is Piper-First. Just create a regular Piper CL. When the
+CL is accepted and submitted, it will make its way to OSS via regular releasing
+process.
diff --git a/googlemock/docs/design.md b/googlemock/docs/design.md
new file mode 100644
index 00000000..3dd40256
--- /dev/null
+++ b/googlemock/docs/design.md
@@ -0,0 +1,1600 @@
+# gMock - a Framework for Writing and Using C++ Mock Classes
+
+<!--#include file="under-construction-banner.md"-->
+
+**Status:** Draft \
+**Tiny URL:** http://go/gmockdesign \
+**Author:** Zhanyong Wan (who/wan)
+
+<!-- GOOGLETEST_CM0035 DO NOT DELETE -->
+
+(To participate in discussions on gMock, please subscribe to
+[opensource-gmock](https://groups.google.com/a/google.com/group/opensource-gmock/subscribe).
+Past discussions can be viewed
+[here](https://groups.google.com/a/google.com/group/opensource-gmock/topics) and
+[here](https://mailman.corp.google.com/pipermail/c-mock-dev/).)
+
+(The slides for my gMock preview talk can be found here:
+[ppt](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0706-beijing-gmock-preview.ppt).)
+
+## Objective
+
+[Mock objects](http://en.wikipedia.org/wiki/Mock_object) are simulated objects
+that mimic real objects in controlled ways. They are useful for driving the
+design of a system, and for testing some other object when it's difficult to use
+real objects in a test.
+
+While the idea of mocks applies to all objected-oriented languages, writing them
+in C++ has many practical difficulties, due to the lack of support for
+reflection in the language, the complexity and irregularity of C++, and the lack
+of adequate tools. As an unfortunate result, C++ programmers often avoid writing
+mocks, resulting in big, monolithic classes in production, and slow, brittle,
+and difficult-to-maintain tests.
+
+We believe that a good framework can make it much more pleasant to write and use
+mocks in C++. Such a tool would help people write more
+[small](https://wiki.corp.google.com/twiki/bin/view/Main/GoogleTestDefinitions)
+tests that are quick, robust, and precise. Perhaps more importantly,
+incorporating mocks early and often in the design process helps people discover
+the role interfaces in the system and thus often leads to
+[better designs](http://www.jmock.org/oopsla2004.pdf).
+
+We plan to develop *gMock* as a generic framework for creating and using mock
+classes in C++. We would encourage people to *use gMock as a design tool as much
+as a testing tool*.
+
+### Goals of gMock
+
+*   **Supporting all interfaces:** A user should be able to use gMock to create
+    a mock class for any C++ interface (i.e. a class whose methods are virtual).
+    In particular, interface templates should be supported, and there should be
+    no restriction on the types of the parameters - `const` parameters, pointer
+    parameters, reference parameters, reference-to-`const` parameters, and etc
+    should all be allowed.
+
+    gMock can also be used to mock a "loose" interface (i.e. the set of
+    operations a template class or template function expects its type argument
+    to support). This is useful for testing code that uses the
+    ["high-performance dependency injection"](https://engdoc.corp.google.com/eng/doc/tott/episodes/33.md)
+    technique.
+
+*   **Precise specification of the intention:** gMock should enable a user to
+    precisely specify the intended behavior of a mock object, and how its
+    methods are expected to be called (in what order, with what arguments, etc).
+    In particular, it should not force the user to over-specify the problem
+    (which results in brittle tests that break when unrelated changes to the
+    code are made), or to under-specify the problem (which results in tests that
+    continue to pass when they shouldn't).
+
+*   **Intuitive and declarative syntax:** A declarative syntax fosters thinking
+    at the right abstraction level, and makes the code readable and less
+    error-prone. Therefore gMock should provide intuitive and declarative syntax
+    for:
+
+    1.  creating a mock class, and
+    2.  controlling the behavior of a mock object. When the two goals conflict,
+        the latter takes precedence, as it usually needs to be done many more
+        times than the former.
+
+*   **Extensible:** No framework can be expected to cover all users' needs.
+    Therefore, gMock shouldn't tie the users to whatever it provides. Instead, a
+    user should be able to easily extend the framework to accomplish more
+    advanced tasks.
+
+*   **Helpful error messages:** Bad error messages are a sure-fire way to
+    frustrate the users and drive them away. Therefore, gMock should generate
+    clear and sensible messages
+
+    1.  when the code fails to compile - this can be hard as lots of templates
+        have to be used in the implementation, but we should try our best; and
+    2.  when a user-supplied expectation fails. This also applies to
+        user-defined extensions, given that the user has done a good job
+        implementing the extensions.
+
+*   **Easy to learn:** We want gMock to make people's life easier, not harder.
+    It defeats our purpose if the framework is complex and difficult to learn.
+
+*   **Easily automatable:** The design of gMock should make the process of
+    creating a mock class from an interface fairly mechanical, and thus doable
+    by the automated
+    [mock class generator](https://wiki.corp.google.com/twiki/bin/view/Main/MockClassGeneratorDev).
+
+*   **Working in Google's environment:** While we may be interested in open
+    sourcing gMock later, our primary goal is to serve Google. Therefore gMock
+    must work well in our environment. In particular, it must not use
+    exceptions, and should work well with
+    [gUnit](https://wiki.corp.google.com/twiki/bin/view/Main/GUnitGuide).
+
+### Non-goals
+
+*   **Mocking non-virtual methods:** gMock is a source-level tool that works
+    with standard compilers and linkers. It doesn't attempt to swap the object
+    code of a mock class and that of a real class on-the-fly. Therefore, only
+    virtual methods and template arguments can be mocked by gMock.
+*   **Supporting arbitrary number of parameters:** Due to limitations of the C++
+    language, there will be a practical limit on the number of parameters a mock
+    function can have. Support for more parameters can be added as needed.
+*   **Supporting non-Linux platforms:** The initial implementation may not run
+    on Windows or Mac OS. We have limited resources and need to make sure that
+    Linux users are served first. However, we'll try to avoid doing things that
+    will make porting gMock to non-Linux platforms difficult.
+*   **Special support for particular projects:** gMock is a generic framework
+    that makes mocking easy for *all* Google C++ projects. It should not contain
+    logic that's useful only to a small number of projects.
+
+## Background
+
+### Terminology
+
+Different people often use "mock" to mean different things. This document
+borrows the terminology popularized by
+<a href="http://www.martinfowler.com/articles/mocksArentStubs.html">Martin
+Fowler</a>:
+
+*   **Dummy** objects are passed around but never actually used. Usually they
+    are just used to fill parameter lists.
+*   **Fake** objects actually have working implementations, but usually take
+    some shortcut (perhaps to make the operations less expensive), which makes
+    them not suitable for production.
+*   **Stubs** provide canned answers to calls made during the test, usually not
+    responding at all to anything outside what's programmed in for the test.
+*   **Mocks** are objects pre-programmed with expectations which form a
+    specification of the calls they are expected to receive.
+
+### Fakes vs Mocks
+
+Many people are not clear about the difference between a fake and a mock, and
+use the terms interchangeably. However, to understand why we need gMock and what
+it will deliver, it's crucial to distinguish the two.
+
+Compared with a fake, a mock object is "dumb" and usually doesn't have a working
+implementation. However, it allows the user to control its behavior and set
+expectations on the calls it will receive. For example, you can tell a mock
+object that its `Foo()` method will be called twice with an argument that's
+greater than 10, and it should return 12 and 14 respectively.
+
+It may seem that mocks are not very useful compared to fakes, but the Java
+community has shown this perception to be wrong. The ability to control a mock
+object's behavior and specify the expected interaction between it and the code
+under test makes it far more flexible and useful than a fake in designing and
+testing a software system.
+
+While fake classes have to be crafted with domain knowledge, mock classes can
+actually be created mechanically - with suitable support from a framework. In
+more dynamic languages like Java, C#, and Python, there are tools that create
+mock objects on the fly without any user intervention. In C++, this cannot be
+done within the language itself. However, a framework can make the task much
+easier for a user, and the
+[mock class generator](https://wiki.corp.google.com/twiki/bin/view/Main/MockClassGeneratorDev)
+will make the process automated to a large extent.
+
+### C++ Mocking at Google
+
+To our knowledge, no tool or library is used at Google to facilitate the
+creation of mock classes. As a result, people have been writing mock classes
+manually. Such classes are typically tedious to create, and lack functionalities
+for effective mocking. As a result, people are often frustrated and decided to
+avoid mock classes.
+
+As a rough estimate, as of 3/15/2007, the number of existing C++ mock classes in
+our source tree is:
+
+```shell
+$ gsearch -f="\.(h|cc|cpp)$" -a -c "^\s*class\s+(Mock\w*|\w+Mock)\s*[:{]"
+748
+```
+
+while the number of all C++ classes is:
+
+```shell
+$ gsearch -f="\.(h|cc|cpp)$" -a -c "^\s*class\s+\w+\s*[:{]"
+188488
+```
+
+Roughly 1 out of every 250 C++ classes has a corresponding mock class. Clearly
+this is not enough.
+
+### Situation outside Google
+
+The situation of using C++ mocks outside of Google is not a lot brighter either.
+Although there is an open-source framework
+([mockpp](http://mockpp.sourceforge.net/)) for writing mock classes, it is
+overly complex and has limited functionalities. As a result, it doesn't have a
+large following.
+
+### Existing Mock Frameworks
+
+A good mock framework takes years of hard work and actual use in the field to
+mature. Therefore, it pays hugely to learn from existing mock frameworks: what
+they can and cannot do, why they are the way they are, how they have evolved,
+what lessons their creators have learned, and what they intend to do next, etc.
+
+We studied some well-known mock frameworks for Java
+([Mock Objects](http://www.mockobjects.com),
+[EasyMock](http://www.easymock.org), [jMock 1](http://www.jmock.org), and
+[jMock 2](http://cvs.jmock.codehaus.org/browse/~raw,r=1.3/jmock/website/content/cheat-sheet.html))
+and for C++ ([mockpp](http://mockpp.sourceforge.net/)). Our conclusion is:
+
+*   Mock Objects is the most primitive of the four. It provides some basic
+    constructs for a user to set expected arguments and return values, but not
+    much beyond that.
+*   EasyMock makes the simple case very easy, but isn't flexible enough to
+    handle more advanced usage well. Often the users are forced to either
+    over-specify or under-specify their intention, resulting in brittle or
+    imprecise tests.
+*   jMock 1 and 2 share the same design philosophy, but have incompatible
+    syntaxes. They allow a user to precisely specify the intention of the test
+    in most cases, and can be easily extended by the user to handle more complex
+    situations.
+*   mockpp is a mixed bag of constructs from the above three. It doesn't have a
+    coherent design philosophy, and doesn't address C++'s specific requirements
+    well. It is more complex, redundant, and difficult to learn and use than we
+    would like.
+
+### Our Plan
+
+We believe that jMock is the most interesting and promising of the four. Its
+creators have been aggressively experimenting with new ideas and designs, and
+have produced many iterations before the current form. They have also documented
+their experience and lessons in developing jMock in
+[two](http://www.jmock.org/oopsla2004.pdf)
+[papers](http://mockobjects.com/files/evolving_an_edsl.ooplsa2006.pdf), which
+contain many valuable insights.
+
+Therefore, the design of gMock is heavily influenced by jMock. Many constructs
+will be directly ported from jMock. Meanwhile, we'll revisit various design
+decisions in C++'s context to make sure that we take advantages of C++ strengths
+and avoid its weaknesses. We will also address some challenges that are unique
+to C++.
+
+## Overview
+
+### Why a Framework
+
+Mock objects serve two distinct purposes in designing and testing a software
+system:
+
+1.  They implement the same interfaces as the real classes and provide canned
+    responses, allowing code that uses them to compile and run; and
+2.  They can verify that the actual interaction between them and the code under
+    test matches what the user expects (for example, the right functions are
+    called, in the right order, with the right arguments, etc).
+
+Without a framework, a user could manually implement mock functions to return
+answers that are either pre-defined or computed using simplified logic. To
+verify that the interaction that actually happens matches the expectation, a
+user would typically let the mock functions record the interaction in some way,
+and inspect the record in the end. This poor man's approach leaves several
+things to be desired:
+
+1.  Writing a mock class manually is not easy, and often viewed as a burden to
+    be avoided.
+2.  Different tests use a mock class in different ways. Therefore, it is often
+    impractical to provide a working fake implementation that is useful for all
+    tests.
+3.  Describing what the interaction should be by inspecting what really has
+    happened is round-about and unnatural. It obscure the intention of the test
+    author, and results in tests that are hard to read and understand.
+4.  It is often too late to check how the interaction went after it has
+    finished. Much better is to report a failure at the exact moment an
+    expectation is violated. This gives the user a chance to check the context
+    of the failure (the stack trace, the variables, etc) before important
+    information is lost.
+
+The purpose of gMock is to address the above problems. In particular, it will:
+
+1.  make the task of writing a mock class much easier by hiding the low-level
+    mechanism from the user;
+1.  let the user of a mock class, rather than its creator, specify the intended
+    responses;
+1.  let the user specify the intended interaction in a clear and direct syntax;
+    and
+1.  catch violations to the specification as soon as they arise.
+
+### gMock's Expressiveness
+
+The Java community's years of experience using mocks shows that a mock framework
+should enable a user to directly specify the following properties of the
+interaction between a mock object and its surrounding code:
+
+*   How many times will a function be called?
+*   What arguments will be used?
+*   In what order will the calls be made?
+*   What should the functions return?
+*   What side effects (if any) should the calls incur?
+
+Also, it's important to be able to loosen the constraints when necessary to
+prevent brittle tests. For example,
+
+*   If the test doesn't care about how many times a function will be called, the
+    test writer should be able to make that clear;
+*   If the exact value of an argument doesn't matter, the user should be able to
+    say so;
+*   If only a subset of the calls need to happen in a strict order, the user
+    should be allowed to specify a partial order.
+
+### Architecture of gMock
+
+gMock is a C++ library that will be linked into a user's test code. It consists
+of the following components (the syntax used in the code samples is
+*tentative*):
+
+1.  **Function mockers:** A family of template classes will be provided for the
+    user to mock functions with different arities. For example, a field of type
+
+    ```
+    FunctionMocker<int(bool, const string&)>
+    ```
+
+    will be used to mock a function with signature
+
+    ```
+      virtual int Foo(bool, const string&);
+    ```
+
+1.  **Specification builder:** This provides a syntax for the user to specify
+    the expected arguments and responses of a mock function. For example, to say
+    that `Foo()` will be called exactly twice with arguments `true` and a string
+    that contains `"hello"`, and will return 10 and 12 respectively, the user
+    can write:
+
+    ```
+    EXPECT_CALL(mock_object, Foo(Eq(true), HasSubstring("hello"))
+      .Times(2)
+      .WillOnce(Return(10))
+      .WillOnce(Return(12))
+    ```
+
+1.  **Cardinalities, matchers, and actions:** A collection of pre-defined
+    *cardinalities* (e.g. `2`), argument *matchers* (e.g. `Eq()` and
+    `HasSubstring()`), and stub *actions* (e.g. `Return()`) will enable the user
+    to precisely specify the intended interaction in most cases. When this set
+    is inadequate, the user can easily define new cardinalities, matchers, and
+    actions.
+
+1.  **Specification interpreter:** An underlying interpreter will verify that
+    the actual calls made to the mock object conform to the user's expectations.
+
+gMock helps a user in two kinds of activities: *writing* mock classes and
+*using* them in tests. When writing a mock class, a user employs the function
+mockers (#1); when using a mock class, the user relies on #2 and #3 to specify
+the expected interaction between the mock object and the code under test. As the
+test runs and the mock functions are invoked, the specification interpreter (#4)
+verifies that the actual interaction matches the expectation, and fails the test
+when the two don't match.
+
+## Detailed Design
+
+### Implementing a Mock
+
+This section explains how a user would implement a mock class using gMock. The
+final syntax may be slightly different to what's presented here, but the overall
+idea should remain the same.
+
+The goal of the design is to allow mocking functions that take 0 or more
+arguments, functions that are overloaded on the number/types of parameters,
+const methods, and methods that are overloaded on the const-ness of this object.
+
+#### Using macros
+
+The easiest way to define a mock class is to use the `MOCK_METHOD` macro.
+Specifically, to mock an interface
+
+```cpp
+class FooInterface {
+  ...
+  virtual R Method(A1 a1, A2 a2, ..., Am am) = 0;
+  virtual S ConstMethod(B1 b1, B2 b2, ..., Bn bn) = 0;
+};
+```
+
+one would simply write
+
+```cpp
+class MockFoo : public FooInterface {
+  ...
+  MOCK_METHOD(R, Method, (A1 a1, A2 a2, ..., Am am), (override));
+  MOCK_METHOD(S, ConstMethod, (B1 b1, B2 b2, ..., Bn bn), (const, override));
+};
+```
+
+#### Using no macro
+
+The user can also choose to implement a mock class without using the macros.
+
+For each function to be mocked that is not overloaded, the user should define a
+**function mocker** member variable and implement the function by forwarding the
+call to the function mocker, which knows how to respond to the given arguments.
+
+A user specifies the mock function's default behavior and expectations on it by
+calling the *mock spec function* in an `ON_CALL()` or `EXPECT_CALL()` statement.
+
+Now let's see the concrete syntax. To mock a function that takes no argument:
+
+```cpp
+class AbcInterface {
+  ...
+  virtual R Foo() = 0;
+};
+```
+
+a user would write:
+
+```cpp
+class MockAbc : public AbcInterface {
+  ...
+  // Mock Foo().  Implements AbcInterface::Foo().
+  virtual R Foo() { return gmock_Foo.Invoke(); }
+
+  FunctionMocker<R()> gmock_Foo;
+};
+```
+
+To mock a function that takes some arguments:
+
+```cpp
+  virtual R Bar(A1 a1, A2 a2);
+```
+
+a user would write:
+
+```cpp
+  virtual R Bar(A1 a1, A2 a2) { return gmock_Bar.Invoke(a1, a2); }
+
+  FunctionMocker<R(A1, A2)> gmock_Bar;
+```
+
+To mock a `const` method:
+
+```cpp
+  virtual R Baz(A1 a1) const;
+```
+
+a user would write:
+
+```cpp
+  virtual R Baz(A1 a1) const { return gmock_Baz.Invoke(a1); }
+
+  mutable FunctionMocker<R(A1)> gmock_Baz;
+```
+
+Mocking overloaded functions is a little bit more involved. For each overloaded
+version, the user needs to define an overloaded mock controller function, e.g.
+
+```cpp
+  virtual R Bar(A a) { return gmock_Bar_1.Invoke(a); }
+  MockSpec<R(A)>& gmock_Bar(Matcher<A> a) {
+     return gmock_Bar_1.With(a);
+  }
+
+  virtual R Bar(B b, C c) { return gmock_Bar_2.Invoke(b, c); }
+  MockSpec<R(B, C)>& gmock_Bar(Matcher<B> b, Matcher<C> c) {
+     return gmock_Bar_2.With(b, c);
+  }
+ private:
+  FunctionMocker<R(A)> gmock_Bar_1;
+  FunctionMocker<R(B, C)> gmock_Bar_2;
+```
+
+If a method is overloaded on the const-ness of this object, the user can
+distinguish between the two overloaded versions by using a const- vs non-const-
+reference to the mock object. The `Const()` function provided by gMock can be
+used to get a const reference to an object conveniently:
+
+```cpp
+template <typename T>
+inline const T& Const(const T& x) { return x; }
+```
+
+### Syntax for Setting Default Actions and Expectations
+
+For each mock function, there are two interesting properties for a user to
+specify:
+
+1.  the **default action**: what the function should do by default when invoked,
+    and
+2.  the **expectations**: how the function will be called in a particular test.
+
+While the default actions of a mock class usually don't change from test to
+test, a user typically sets different expectations in different tests.
+
+The following syntax is proposed for setting the default action of and the
+expectations on a mock function:
+
+```cpp
+ON_CALL(mock-object, method(argument-matchers))
+  .With(multi-argument-matcher) ?
+  .WillByDefault(action);
+```
+
+The `ON_CALL()` statement defines what a mock function should do when its
+arguments match the given matchers (unless the user overrides the behavior in
+`EXPECT_CALL()`). The `With()` clause is optional. The `WillByDefault()` clause
+must appear exactly once.
+
+```cpp
+EXPECT_CALL(mock-object, method(argument-matchers))
+  .With(multi-argument-matcher) ?
+  .Times(cardinality) ?
+  .InSequence(sequences) *
+  .WillOnce(action) *
+  .WillRepeatedly(action) ?
+  .RetiresOnSaturation(); ?
+```
+
+The `EXPECT_CALL()` statement says that the mock function should be called the
+given number of times (`cardinality`), in the order determined by the
+`sequences`, and with arguments that satisfy the given `matchers`. When it is
+called, it will perform the given `action`. In this statement, all clauses are
+optional and you can repeat `WillOnce()` any number of times. When no action is
+specified, the default action defined by `ON_CALL()` will be taken.
+
+For non-overloaded methods, '(argument-matchers)' may be omitted:
+
+```cpp
+ON_CALL(mock-object, method)
+  .With(multi-argument-matcher) ?
+  .WillByDefault(action);
+
+EXPECT_CALL(mock-object, method)
+  .With(multi-argument-matcher) ?
+  …cardinality and actions…
+```
+
+This allows test writers to omit the parameter list and match any call to the
+method. Doing so eases the burden on test maintainers when refactoring method
+signatures. The 'With()' clause is still optional when the parameter list is
+omitted.
+
+We make `ON_CALL()` and `EXPECT_CALL()` macros such that we can tell the mock
+object the file name and line number of a rule, which can be used to produce
+better error messages at run time. When running a test inside Emacs and an
+expectation is violated, the user can jump to the expectation by hitting
+`<return>` on the message.
+
+#### Argument Matchers
+
+An `argument-matcher` can be any of the following:
+
+```cpp
+Void(), Eq(value), Ge(value), Gt(value), Le(value), Lt(value), Ne(value),
+HasSubstring(string), SubstringOf(string),
+Same(value), Anything(), Any<type>(), Not(argument-matcher), AnyOf(argument-matchers), AllOf(argument-matchers)
+```
+
+In addition, a user can define custom matchers by implementing the
+`MatcherImplInterface<type>` interface (TBD).
+
+#### Multi-argument Matchers
+
+Matchers in the previous section match one argument at a time. Sometimes it's
+necessary to check all arguments together. This is when multi-argument matchers
+are needed:
+
+```cpp
+Eq(), Ge(), Gt(), Le(), Lt(), Ne(),
+HasSubstring(), SubstringOf(),
+Same(), AnyThings(), Not(multi-argument-matcher), AnyOf(multi-argument-matchers), AllOf(multi-argument-matchers)
+```
+
+When there are multiple `WithArguments()` clauses in a rule, all of them have to
+be satisfied for the rule to match a call.
+
+A user can define new multi-argument matchers by implementing the
+`MatcherImplInterface<std::tuple<type1, ..., type_n> >` interface (TBD).
+
+#### Actions
+
+```cpp
+Return(), Return(value), DoDefault(), Fail(string),
+SetArgPointee<N>(value), DoAll(actions), ...
+```
+
+The version of `Return()` that takes no argument is for mocking `void`-returning
+functions. The clauses are all statically typed, so a user won't be able to
+mistakenly use `Return()` when the mocked function has a non-void return type,
+or to use `Return(value)` when the function returns `void`.
+
+On consecutive calls that match a given expectation, actions specified in
+multiple `WillOnce()` clauses in the expectation will be used in the order they
+are presented. After all `WillOnce()` clauses have been exhausted, the action
+specified by `WillRepeatedly()` will always be used. If there is no
+`WillRepeatedly()`, the default action defined by `ON_CALL()` will be taken.
+
+When side effects need to be mocked (e.g. changing a field or a global variable,
+calling a function of a class-typed argument, and so on), users can define a
+custom action by implementing the `ActionImplInterface<return-type(type1, ...,
+type-n)>` interface (TBD).
+
+#### Cardinalities
+
+A cardinality tells how many times a function is expected to be called. The
+number doesn't have to be always exact, as we don't want to over-specify the
+behavior and result in brittle tests.
+
+```cpp
+integer, AtLeast(n), AtMost(n), Between(m, n), AnyNumber()
+```
+
+This set can be extended by the user implementing the `CardinalityImplInterface`
+interface (TBD).
+
+If no cardinality is specified in an `EXPECT_CALL()` statement, gMock will infer
+it this way:
+
+*   If there are n `WillOnce()` clauses but no `WillRepeatedly()`, the
+    cardinality is n;
+*   If there are n `WillOnce()` clauses and a `WillRepeatedly()`, the
+    cardinality is `AtLeast(n)`.
+
+#### Sequences
+
+Often we want to specify the order in which mock functions are called. However,
+we may not want to specify a total order as that may lead to flaky tests that
+will be broken by unrelated changes. For this reason, gMock allows the user to
+specify a partial order on the calls by organizing them into *sequences*.
+
+Basically, a sequence is a chain of expectations that have to happen in the
+order they are defined. Sequences are identified by their names. For example,
+the following defines a sequence named `"a"`, which contains two expectations
+where the first has to happen before the second:
+
+```cpp
+  Sequence a;
+
+  EXPECT_CALL(mock_foo, Func1(Anything()))
+     .Times(1)
+     .InSequence(a);
+
+  EXPECT_CALL(mock_bar, Func2(Eq(2)))
+     .Times(3)
+     .InSequence(a);
+```
+
+Note that expectations in the same sequence don't have to be on the same object
+or same function, as the above example shows.
+
+An expectation can belong to any number of sequences, in which case all order
+constraints have to be honored. For convenience, we allow `InSequence()` to take
+multiple sequences. In the following example, the first expectation must be
+matched before the second and the third, but we don't care about the relative
+order of the latter two:
+
+```cpp
+  Sequence a, b;
+
+  EXPECT_CALL(mock_foo, Func1(Anything()))
+     .Times(1)
+     .InSequence(a, b);
+
+  EXPECT_CALL(mock_bar, Func2(Eq(2)))
+     .Times(AnyNumber())
+     .InSequence(a);
+
+  EXPECT_CALL(mock_bar, Func2(Eq(5)))
+     .Times(AnyNumber())
+     .InSequence(b);
+```
+
+For convenience, we allow an expectation to contain multiple `InSequence()`
+clauses, in which case their arguments will be joined. For example, another way
+to write the first expectation in the above example is:
+
+```cpp
+  EXPECT_CALL(mock_foo, Func1(Anything()))
+     .Times(1)
+     .InSequence(a)
+     .InSequence(b);
+```
+
+A common scenario is that the user wants all expectations to match in the strict
+order they are defined. Instead of letting the user put `InSequence()` in every
+expectation, we provide the following short-hand:
+
+```cpp
+  {
+     InSequence s;
+
+     EXPECT_CALL(...)...;
+     EXPECT_CALL(...)...;
+     ...
+  }
+```
+
+In the above snippet, when the variable `s` is constructed, gMock will generate
+a unique new sequence and automatically put each `EXPECT_CALL()` in the scope of
+`s` into this sequence. The result is that this group of expectations must match
+in the strict order.
+
+The user can also use an existing sequence like this:
+
+```cpp
+  Sequence a;
+  ...
+  {
+     InSequence s(a);
+
+     EXPECT_CALL(...)...;
+     EXPECT_CALL(...)...;
+     ...
+  }
+```
+
+This can be useful if an existing sequence needs to be extended.
+
+#### Examples
+
+```cpp
+EXPECT_CALL(mock_goat, Eat(Eq(5), Anything()))
+  .WillOnce(Return(false));
+```
+
+The mock goat will be told to `Eat()` 5 of something exactly once; the method
+should return `false`.
+
+```cpp
+EXPECT_CALL(mock_goat, Drink(HasSubstring("milk")))
+  .Times(1);
+```
+
+The mock goat will be told to `Drink()` something that contains milk once; the
+method should perform its default action when invoked.
+
+```cpp
+EXPECT_CALL(mock_elephant, Eat(Same(mock_goat)))
+  .Times(0);
+```
+
+The mock elephant should never be told to `Eat()` the poor mock goat, which
+would be a terrible thing.
+
+```cpp
+Sequence a;
+
+EXPECT_CALL(mock_elephant, Eat(Anything()))
+  .InSequence(a)
+  .WillOnce(Return(true));
+
+EXPECT_CALL(mock_elephant, Walk(Ge(5)))
+  .Times(AtLeast(1))
+  .InSequence(a)
+  .WillOnce(Return(2));
+```
+
+The mock elephant will be told to `Eat()` something; after that it will be told
+to `Walk()` >= 5 meters at least once; the `Walk()` method should return 2 the
+first time, and should do the default action in future calls.
+
+#### Syntax Checking
+
+We will use a combination of compile-time and run-time checks to catch syntax
+errors. In particular, the spelling and types of the individual clauses will
+(obviously) be done by the C++ compiler, while we'll enforce the order and
+counts of the clauses via run-time checks.
+
+Please note that technically it is possible to do the latter checks at compile
+time too, and that is the approach of jMock and Mockpp. For the designer of an
+embedded domain-specific language (EDSL), it is appealing to leverage the
+compiler of the hosting language (C++ in this case) to parse code in the EDSL
+and catch errors in it as much as possible. It is also an interesting exercise
+in pushing the envelope of EDSL implementation techniques.
+
+However, while we initially wanted to go with jMock's approach, we now think
+it's better to defer such checks to run time. The reasons are:
+
+1.  Doing the checks at run time *significantly* reduces the number of template
+    classes and simplifies the implementation. This is not only a benefit for
+    the author and maintainer of gMock, but also makes it much easier for a user
+    to learn gMock. New and existing users will have to read the gMock header
+    files from time to time, so it's important to keep the public interface
+    small. As an example of what happens when the API is not kept small, try to
+    read the header files of Mockpp - you will find a plethora of template
+    classes that reference each other, and it's very difficult to tell what
+    different roles they play.
+1.  The jMock approach enables the IDE to automatically suggest the next clause
+    when a user is writing an expectation statement and thus makes it trivial to
+    write syntactically correct expectations. Unfortunately, such benefit is
+    merely theoretic for most C++ users, as C++ is such a complex language that
+    most IDEs do a poor job at understanding the user's source code and
+    suggesting auto-completion.
+1.  C++ templates generate horrible, horrible compiler errors that often baffle
+    even experienced programmers. By enforcing the syntax at compile time, we
+    subject gMock's users to the mercy of the C++ compiler, which will generate
+    lengthy and cryptic errors when a user makes a small mistake in the syntax.
+    It would be much better for us to generate the errors at run time, as we can
+    control the messages and choose plain and clear language that guides the
+    user to fix the problem.
+1.  The default action and expectation statements in gMock are *declarative*,
+    and typically each of them will be executed once during the test (not to be
+    confused with a rule *matching* an invocation multiple times). Therefore
+    there should be little concern that a syntax error is not caught because the
+    statement is never actually executed.
+
+### Formal Semantics
+
+The previous section presented the syntax and informally explained the meanings
+of various clauses. To avoid ambiguities and make sure we all have the same
+understanding on the meaning of a complete test using mock objects, we need to
+define the semantics of gMock more strictly.
+
+For an expectation rule to match an actual invocation, three types of
+constraints have to be satisfied at the same time:
+
+1.  the order constraints (does the call occur in the right order?),
+2.  the cardinality constraints (can the rule accept more invocations?), and
+3.  the argument constraints (do all arguments satisfy their matchers?).
+
+As the designer of gMock, we need to decide in which order these constraints
+should be applied and how to resolve ambiguities. Our goal is to choose a
+semantics that is easy to understand and allows the user to easily express
+properties useful for writing tests.
+
+Given that gMock borrows heavily from jMock, naturally one would try to adopt
+jMock's semantics. I couldn't find a documentation on that unfortunately. The
+following semantics is based on my reverse-engineering jMock and what I think is
+reasonable. It differs from the jMock semantics in several important regards.
+The exact differences and the rationale behind our decision can be found on the
+c-mock-dev [archive](https://g.corp.google.com/group/c-mock-dev-archive) and are
+not repeated here.
+
+The proposed semantics can be summarized by two simple principles:
+
+1.  **The orders are sacred**: under no circumstance can an expectation in a
+    sequence to match before all expectations that appear earlier in the same
+    sequence have been satisfied; and
+2.  **Earlier rules take precedence:** when multiple rules can match an
+    invocation without violating the order constraints, the one defined the
+    earliest wins.
+
+To define the semantics formally, we will use the following terminology:
+
+*   An `ON_CALL()` statement defines a **default action**.
+*   An `EXPECT_CALL()` statement defines an **expectation**.
+*   An expectation is **active** iff it still can be used to match invocations.
+    Otherwise it is **retired**. Initially, all expectations are active.
+*   An expectation X is an **immediate pre-requisite** of another expectation Y
+    iff there exists a sequence S where X and Y are both in S, X is defined
+    before Y, and there is no expectation in S between X and Y.
+*   An expectation X is a **pre-requisite** of another expectation Y iff there
+    exists a list X[0] = X, X[1], ..., X[n] = Y, where X[i] is an immediate
+    pre-requisite of X[i+1] for all i.
+*   An expectation (or its cardinality constraint) is said to be **satisfied**
+    iff it has reached its minimum number of allowed invocations.
+*   An expectation (or its cardinality constraint) is said to be **saturated**
+    iff it has reached its maximum number of allowed invocations. A saturated
+    expectation by definition must be satisfied, but not vice versa.
+
+After the user has set the default action and the expectations, when a mock
+function is called, the following algorithm (in pseudo code) will be used to
+find the matching expectation and the matching action:
+
+```cpp
+void TryToDoDefault(FunctionMocker& m, const Arguments& args) {
+  if (m has a default action for arguments args) {
+     perform the default action;
+  } else {
+     raise error("No action is specified.");
+  }
+}
+
+void OnInvocation(FunctionMocker& m, const Arguments& args) {
+  for_each (active expectation e on function m in the order
+                the expectations are defined) {
+     if (all pre-requisites of e are satisfied &&
+          args match e's argument matchers) {
+        // We found a match!
+
+        if (e.is_saturated)
+          raise error("Invocation upper bound exceeded.");
+
+        e.invocation_count++;
+        retire all prerequisites of e;
+
+        if (e.retires_on_saturation && e.is_saturated)
+          e.is_active = false;
+
+        if (e has more action left) {
+          a = e.get_next_action();
+          perform a;
+        } else {
+          TryToDoDefault(m, args);
+        }
+        return;
+     }
+  }
+
+  TryToDoDefault(m, args);
+}
+```
+
+To find the default action for the given arguments, we look through all
+`ON_CALL()` rules for the mock function, and pick the first one where all
+argument matchers are satisfied, if any.
+
+Since C++ exceptions are disabled in `google3`, **we will abort the current
+process when gMock raises an error**. We cannot just return from the current
+function like what gUnit does, as the mock functions will be called from the
+production code under test, and we don't have the luxury to change the
+production code at each call site to propagate the error. This is unfortunate,
+but I don't see a better solution without enabling exceptions.
+
+The real implementation will be more sophisticated in order to get a decent
+performance (e.g. we'll memoize and use other tricks), but the end result must
+match the above reference implementation.
+
+**Note:** If you carefully inspect the algorithm, you should convince yourself
+that an expectation whose cardinality is `0` has no effect whatsoever, as it is
+always satisfied and saturated. This means that you can write such an
+expectation, but it won't affect your test in any way. Indeed, this is jMock's
+behavior, and jMock's documentation suggests to use `Never()` (jMock's
+equivalent of the `0` cardinality) for documentation purpose only.
+
+This bothers me as it contradicts with what one would naturally expect. When I
+see
+
+```cpp
+  EXPECT_CALL(mock_foo, Bar(Eq(5)))
+     .Times(0);
+```
+
+I would think that it will be an error if `mock_foo.Bar(5)` is ever called, and
+gMock will catch this error at run time. However, jMock tells me that it will
+not try to enforce this, and I should treat the statement as if it doesn't
+exist.
+
+I propose to give `Times(0)` a semantics that I think is more intuitive. Namely,
+we should treat
+
+```cpp
+  EXPECT_CALL(mock-object, method(argument-matchers))
+     .WithArguments(multi-argument-matcher)
+     .Times(0)
+     .InSequence(sequences);
+```
+
+as if it were
+
+```cpp
+  EXPECT_CALL(mock-object, method(argument-matchers))
+     .WithArguments(multi-argument-matcher)
+     .Times(AnyNumber())
+     .InSequence(sequences)
+     .WillOnce(Fail("Unexpected call."));
+```
+
+I don't like making this a special case, but the other choice seems worse.
+
+**Note:** If a call doesn't match any explicitly written `EXPECT_CALL()`
+statement, gMock will perform the default action (as long as it exists) instead
+of raising an "unexpected call" error. If you want to assert that a function
+should never be called, you must explicitly write an `EXPECT_CALL()` with a `0`
+cardinality. This design is picked to allow modular tests:
+
+An interface may contain many methods. Typically, each test will be interested
+in only a small number of them, as we favor small and focused tests. Such a test
+shouldn't start to fail when the code under test is modified to call functions
+not interesting to the test. If no `EXPECT_CALL()` were to mean "no call is
+allowed", we would have to say
+
+```cpp
+  EXPECT_CALL(mock_foo, UninterestingMethod(Anything()))
+     .Times(AnyNumber());
+```
+
+for **every** method we do **not** care about. It can be very tedious. Worse,
+when we add methods to the interface or remove methods from it, we have to
+update every existing test. Clearly this isn't modular and won't scale.
+
+#### Examples
+
+If you are not interested in whether a function will be called or not, you just
+don't say anything about it. If the function is called, its default action will
+be performed.
+
+If you want to make sure that a function is never called, say it explicitly:
+
+```cpp
+  EXPECT_CALL(mock_foo, Bar).Times(0);
+  // or:
+  EXPECT_CALL(mock_foo, Bar(Anything())).Times(0);
+```
+
+If you expect certain calls to a function and want to ignore the rest, just
+specify the calls you are explicitly expecting:
+
+```cpp
+  EXPECT_CALL(mock_foo, Bar(Eq(1)))
+     .WillOnce(Return(2));
+  EXPECT_CALL(mock_foo, Bar(Eq(2)))
+     .Times(AtMost(5))
+     .WillRepeatedly(Return(3));
+```
+
+If you expect certain calls to a function and don't want to allow any other
+calls to it, just add a `Times(0)` expectation **after** the normal
+expectations:
+
+```cpp
+  EXPECT_CALL(mock_foo, Bar(Eq(1)))
+     .WillOnce(Return(2));
+  EXPECT_CALL(mock_foo, Bar(Eq(2)))
+     .Times(AtMost(5))
+     .WillRepeatedly(Return(3));
+
+  // Any call to mock_foo.Bar() that doesn't match the above rules
+  // will be an error.
+  EXPECT_CALL(mock_foo, Bar(Anything()))
+     .Times(0);
+```
+
+Here's one complete example:
+
+```cpp
+  ON_CALL(mock_foo, Bar(Anything()))
+     .WillByDefault(Return(1));
+
+  Sequence x;
+
+  EXPECT_CALL(mock_foo, Bar(Ne('a')))     // Expectation #1
+     .InSequence(x)
+     .WillOnce(Return(2))
+     .WillRepeatedly(Return(3));
+
+  EXPECT_CALL(mock_foo, Bar(Anything()))  // Expectation #2
+     .Times(AnyNumber())
+     .InSequence(x);
+
+  mock_foo.Bar('b');  // Matches expectation #1; returns 2.
+  mock_foo.Bar('c');  // Matches expectation #1; returns 3.
+  mock_foo.Bar('b');  // Matches expectation #1; returns 3.
+  mock_foo.Bar('a');  // Matches expectation #2; returns 1.
+
+  // Now that expectation #2 has been used, expectation #1 becomes
+  // inactive (remember that the order is sacred), even though it's not
+  // yet saturated.
+
+  mock_foo.Bar('b');  // Matches expectation #2, returns 1.
+```
+
+Another one:
+
+```cpp
+  Sequence a, b;
+
+  EXPECT_CALL(mock_foo, Func1(Void()))      // #1
+     .Times(1)
+     .InSequence(a);
+
+  EXPECT_CALL(mock_bar, Func2(Anything())   // #2
+     .Times(AtLeast(1))
+     .InSequence(   b);
+
+  EXPECT_CALL(mock_foo, Func3(Eq(0)))  // #3
+     .Times(AtMost(2))
+     .InSequence(a, b);
+
+  EXPECT_CALL(mock_foo, Func3(Anything()))      // #4
+     .InSequence(a);
+
+  // The order constraints can be illustrated as
+  //
+  //    #1 < #3 < #4
+  //    #2 < #3
+
+  mock_foo.Func1();  // Matches #1
+  // Now #1 is saturated but not retired.
+  // If Func1() is called again here, it will be an upper-bound error.
+
+  // It would be an error to call mock_foo.Func3(0) here, as #2 is its
+  // pre-requisite and hasn't been satisfied.
+
+  mock_bar.Func2(1);  // Matches #2, which is now satisfied.
+
+  mock_foo.Func3(1);
+  // Matches #4.  This causes all of #4's remaining pre-requisites (#2
+  // and #3) to become inactive.  Note that #3 is trivially satisfied
+  // as that AtMost(2) doesn't require it to match any invocation.
+```
+
+Yet another one:
+
+```cpp
+EXPECT_CALL(mock_foo, Func(Eq(1)))       // #1
+  .WillOnce(Return(2))
+  .RetiresOnSaturation();
+
+EXPECT_CALL(mock_foo, Func(Anything()))  // #2
+  .WillOnce(Return(3));
+
+mock_foo.Func(1);  // Matches #1.
+// Now #1 is satisfied, saturated, and retired.
+
+mock_foo.Func(1);  // Matches #2.
+// Since #1 is retired now, it doesn't participate in matching function
+// calls.  Otherwise this would cause an upper-bound-exceeded failure.
+```
+
+### Verifying that All Expectations Are Satisfied
+
+During a test, gMock will verify that each invocation to a mock function matches
+one of the expectation rules. However, at the end of a test, we will want to
+verify that *all expectations for the mock function have been satisfied*. This
+is done by the destructor of the `FunctionMocker<...>` class:
+
+### Life of a Mock
+
+Now let's put the pieces together and see the complete process of using mock
+objects in a test. Typically, the user should do it in the following order:
+
+*   **C:** *Constructs* the mock objects;
+*   **B:** Set their default **behaviors** using `ON_CALL()`;
+*   **E:** Set **expectations** on them using `EXPECT_CALL()`;
+*   **I:** Exercise the production code, which will **invoke** methods of the
+    mock objects;
+*   **D:** *Destructs* the mock objects, which will cause gMock to verify that
+    all expectations are satisfied.
+
+Usually, the user can do step 1 and 2 during the set-up phase of the test, step
+3 and 4 in the test function body, and step 5 in the tear-down phase.
+
+If the user performs a step out of sequence (e.g. an `EXPECT_CALL()` is
+encountered after the mock function is already been called by the test and
+before `Verify()` is called), the behavior is **undefined**. gMock will try to
+print a friendly error message, but doesn't guarantee to catch all possible
+violations, and the initial version may not implement this error check at all.
+
+Valid sequences of using a mock object can be described using the regular
+expression
+
+```none
+CB*E*I*D
+```
+
+### Typing of Argument Matchers
+
+Argument matchers in gMock are statically typed. If we don't provide automatic
+conversion between matchers of "compatible" types, the user experience will be
+rather unpleasant. Covariance and contravariance are two common schemes for
+imposing a sub-typing relation between types. Our observation is that neither
+works for matchers in general, and gMock must leave the decision to individual
+matcher authors.
+
+#### Background: How Argument Matchers Work
+
+In gMock, argument matchers are used to determine if the actual arguments in a
+function invocation match the test writer's expectation. Conceptually, a matcher
+for arguments of type `T` implements the following interface:
+
+```cpp
+class Matcher<T> {
+  virtual bool Matches(T x) = 0;
+};
+```
+
+For a method with argument type `T`:
+
+```cpp
+virtual void Func(T x);
+```
+
+its mock will be declared as something like (the actual declaration will be more
+complicated but the idea remains the same):
+
+```cpp
+void Func(Matcher<T>* x);
+```
+
+When the mock `Func()` is invoked with an argument value `v`, which has type
+`T`, `Matches(v)` will be called to determine if it's a match.
+
+#### Need for Sub-typing
+
+A straightforward way to mock a method with parameter types `T1`, `T2`, ..., and
+`Tn` is to use a list of matchers of type `Matcher<T1>`, `Matcher<T2>`, ..., and
+`Matcher<Tn>`. However, this simplistic approach has a usability problem.
+Suppose we have a series of functions and their mocks:
+
+```cpp
+void Func1(char a);
+void Func1(Matcher<char>* a);
+
+void Func2(const char a);
+void Func2(Matcher<const char>* a);
+
+void Func3(char& a);
+void Func3(Matcher<char&>* a);
+
+void Func4(const char& a);
+void Func4(Matcher<const char&>* a);
+
+void Func5(char* a);
+void Func5(Matcher<char*>* a);
+
+void Func6(const char* a);
+void Func6(Matcher<const char*>* a);
+```
+
+(note that `Func2()` has a `const` parameter. Since argument matchers are not
+allowed to modify the arguments in any case, technically we could use a
+`Matcher<char>` in the mock of `Func2()`. However, we want to make sure that a
+user can define the mock using a `Matcher<const char>` too, as this makes the
+task of the mock class generator easier.) and some simple, pre-defined matcher
+factories:
+
+```cpp
+// Matches if the argument equals the given value x.
+Matcher<T>* Eq(T x);
+
+// Matches if the argument has the same identify as the
+// given object x.
+Matcher<T&>* Same(T& x);
+```
+
+then a user might be surprised when trying to use these mocks:
+
+```cpp
+  Func1('a');       // Invokes the real method.  This works fine.
+  Func1(Eq('a'));  // Invokes the mock method.  This works fine too.
+
+  Func2('a');       // Invokes the real method.  This works fine.
+  Func2(Eq('a'));  // Compiler ERROR - surprise!!!  Why can't I say that
+                         // the argument, which is a const char, should be equal
+                         // to 'a'?
+
+  char a = 'a';
+  Func3(a);       // Invokes the real method.  This works fine.
+  Func3(Same(a));  // Fine.  The argument should reference the variable a.
+  Func3(Eq('a'));  // Compiler ERROR - surprise!!!  Why can't I say that
+                         // the argument, which is a char&, should have a value
+                         // 'a', which is a char?
+
+  const char b = 'b';
+  Func4(b);       // Fine.
+  Func4(Same(b));  // Fine.  The argument should reference the variable b.
+  Func4(Eq(b));  // Compiler ERROR - surprise!!!  Why can't I say that
+                         // the argument, which is a const char&, should have
+                         // a value equal to b, which is a const char?
+  Func4(Same(a));  // Compiler ERROR - surprise!!!  Why can't I say that
+                         // the argument, which is a const char&, should reference
+                         // a, which is a char?
+
+  char* p = NULL;
+  Func5(p);       // Fine.
+  Func5(Eq(p));  // Fine.
+
+  Func6("a");       // Fine.
+  Func6(Eq("a"));  // Fine.
+  Func6(Eq(p));  // Compiler ERROR - surprise!!!  Why can't I say that
+                         // the argument, which is a const char*, should point
+                         // to where p, which is a char*, points to?
+```
+
+(In Java, this issue isn't nearly as severe, as Java has neither reference nor
+`const`. Lucky them.)
+
+The compiler errors can be worked around using explicit template instantiating
+in most cases, but require more dirty hacks in some others:
+
+```cpp
+  // The following works:
+  Func2(Eq<const char>('a'));
+  Func4(Eq<const char&>(b));
+  Func4(Same<const char>(a));
+  Func6(Eq<const char*>(p));
+
+  // but this doesn't:
+  Func3(Eq<char&>('a'));  // Compiler ERROR!
+
+  // You have to use a temporary variable, and pray that it's not
+  // accidentally changed before the actual invocation occurs.
+  // No, you cannot make the temporary variable const - that won't
+  // compile.
+  char temp = 'a';
+  Func3(Eq<char&>(temp));
+```
+
+Having to use these tricks all the time is a big bummer and makes the tests
+harder to read. The author of Mockpp either chose to ignore this problem, or
+wasn't aware of it, but I don't think that's a good solution.
+
+To give the user a satisfying experience, I believe we should provide automatic
+conversions between matchers of "compatible" types when it makes sense (i.e. we
+should establish a sub-typing relation between matcher types). The challenges
+are:
+
+1.  Deciding when "it makes sense",
+1.  Making sure the conversions are neither too restricted nor too liberal,
+1.  Making it possible for the user to understand the compiler errors when
+    automatic conversions cannot be done,
+1.  Making the rules easy to learn and remember, and
+1.  Implementing it.
+
+#### Covariant or Contravariant?
+
+We already know that making the matchers **invariant** (i.e. no auto-conversion
+between matcher types) doesn't work, but what about **covariant** (`Matcher<A>`
+can be used as `Matcher<B>` as long as `A` can be used as `B`) or
+**contravariant** (`Matcher<A>` can be used as `Matcher<B>` as long as `B` can
+be used as `A`)? Would one of them work?
+
+It's easy to see that covariance doesn't work in general, as it requires a
+matcher expecting a sub-type value to inspect a super-type value. What if the
+matcher needs to look at a field that's only present in the sub-type?
+
+On the surface level, it seems that contravariance is what we need: if type `B`
+can be implicitly converted to type `A`, then given an argument of type `B`, we
+can convert it to type `A` and then ask a `Matcher<A>` whether the converted
+value matches. This means that we can use a `Matcher<A>` in place of a
+`Matcher<B>`.
+
+For example, given a class hierarchy and some (real and mock) functions that use
+the classes:
+
+```cpp
+class Father { ... };
+
+class Son : public Father {
+ public:
+  ...
+  // New method not present in Father:
+  virtual bool PropertyFoo() const;
+};
+
+class Grandson : public Son { ... };
+
+void InviteFather(Father* obj);
+void InviteFather(Matcher<Father*>* m);
+
+void InviteGrandson(Grandson* obj);
+void InviteGrandson(Matcher<Grandson*>* m);
+```
+
+we can expect to write the following:
+
+```cpp
+// Matches if the argument's PropertyFoo() method returns true.
+Matcher<Son*>* HasFoo() { ... }
+
+// The compiler should reject this as a Father object doesn't have
+// the PropertyFoo() method:
+//
+//  InviteFather(HasFoo());
+
+// This should work, as a Grandson object is also a Son object and
+// has the PropertyFoo() method.
+InviteGrandson(HasFoo());
+```
+
+In the latter case, the actual argument (of type `Grandson*`) will be implicitly
+converted to a `Son*` and then passed to the matcher.
+
+However, things are not always so simple. Take the example of the equality
+matcher, `Func5()`, and `Func6()` we saw earlier:
+
+```cpp
+// Matches if the argument equals the given value x.
+Matcher<T>* Eq(T x);
+
+void Func5(char* a);
+void Func5(Matcher<char*>* a);
+
+void Func6(const char* a);
+void Func6(Matcher<const char*>* a);
+```
+
+By making matchers contravariant, we have
+
+```cpp
+  // Remember that a char* can be implicitly converted to a const char*.
+
+  Func5(Eq("a"));  // Compiles, but we DON'T want it to!!!  The user is
+                         // trying to say that the actual argument (a char*)
+                         // can be "a", and we should catch this error.
+
+  char* p = ...;
+  Func6(Eq(p));  // Still a compiler ERROR, as a const char* cannot be
+                         // implicitly converted to a char*, which Eq(p) expects.
+```
+
+Clearly this isn't what we want. In fact, we want `Eq(value)` to be covariant:
+
+```cpp
+  char* p = ...;
+
+  Func5(p);
+  Func5(Eq(p));
+  // Func5("a");        // The compiler will reject this,
+  // Func5(Eq("a"));  // and thus should reject this too.
+
+  Func6("a");
+  Func6(Eq("a"));
+  Func6(p);           // The compiler accepts this,
+  Func6(Eq(p));      // and thus should accept this too.
+```
+
+In another example:
+
+```cpp
+void InviteSon(Son* obj);
+void InviteSon(Matcher<Son*> m);
+
+Father* father = ...;
+Grandson* grandson = ...;
+
+InviteSon(grandson);         // The compiler accepts this,
+InviteSon(Eq(grandson));    // and thus should accept this too.
+
+// InviteSon(father);       // The compiler will reject this,
+// InviteSon(Eq(father));  // and thus should reject this too.
+```
+
+So, what was the problem? The key insight here is that *one size doesn't fit
+all*. While some matchers should be contravariant (like `HasFoo()`), some should
+be covariant (like `Eq(value)` and `Same(object)`). *The decision has to be left
+to the individual matcher authors. gMock should not impose a global policy on
+all the matchers.*
+
+#### Implementing Automatic Type Conversion
+
+In C++, you have several options if you want to make one class `A` act like
+another class `B`:
+
+1.  Derive `A` from `B`;
+1.  In class `B`, define a public single-parameter constructor `B::B(const A&)`
+    (don't make it `explicit`);
+1.  In class `A`, define a type-conversion operator for type `B`.
+
+Each of these approaches has its limitations:
+
+*   #1 is most straightforward and requires the least amount of work. However,
+    it means that an `A` object will contain all the members of `B`. It may not
+    work for you if you want to be able to auto-convert `A` to multiple classes,
+    and it certainly won't work if you want to convert `A` to an infinite number
+    of other classes.
+*   #2 requires you to be able to edit the implementation of `B`. This is not
+    always possible, for example, when `B` is a class defined in a standard
+    library and you are a user of that library. It's a closed approach, meaning
+    that only the owner of `B` can decide which classes can be converted to `B`.
+*   #3 requires more work to implement typically, but doesn't have the problems
+    of #1 and #2. In particular, you can define a template type-conversion
+    operator to convert `A` to an infinite number of other classes of your
+    choice.
+
+Also, remember that the compiler will only automatically insert one level of
+type conversion on your behalf. For example, if `A` can be implicitly converted
+to `B`, which can be implicitly converted to `C`, and you have a function
+expecting a `C`, you cannot give the function an `A` without explicit casting,
+unless `A` can be implicitly converted to `C` too.
+
+gMock defines the `Matcher<T>` interface, which a user cannot modify. When
+defining a polymorphic matcher (e.g. `Eq(value)`), a user needs to make it
+behave like a (potentially infinite) number of matchers of different types. This
+means that the last implementation technique should be used.
+
+### Comparison with Mockpp and jMock
+
+See GMockVsMockppAndJMock.
+
+## Project
+
+This design doc describes the project "[gMock](http://p?p=6164) - a framework
+for writing C++ mock classes" in PDB.
+
+## Code Location
+
+This is a new project, so no existing file is expected to be touched. The
+implementation is added in directory `//depot/google3/testing/base`.
+
+## Group Members
+
+ZhanyongWan : spending 60% of his time on this.
+
+## Caveats
+
+We considered existing solutions, but don't think they would work well enough
+for Google. For details, please refer to MockppStudy.
+
+TODO:
+
+*   Explain why we pick the EDSL-style syntax.
+
+## Documentation Plan
+
+In additional to this design doc, a user's guide, an FAQ, and a codelab will
+also be written.
+
+## Testing Plan
+
+gMock will be thoroughly tested on Linux using gUnit.
+
+## Work Estimates
+
+*   **Inspecting existing solutions:** The goal is to understand how other
+    people have approached this problem, what they did well, and what did
+    poorly. In addition to studying solutions for C++ (mockpp), we will also
+    study solutions for Java (jMock and EasyMock). **3 weeks.**
+*   **Initial design and prototyping:** Come up with a design tailored to C++'s
+    specifics and Google's unique requirements, taking into account lessons
+    learned from other solutions. **3 weeks.**
+*   **Soliciting feedback on the design:** Listen to `testing-technology`,
+    `testing-grouplet`, `c-users`, `c-mock-dev`, and `gunit-users`; revise the
+    design based on the feedback. **3 weeks.**
+*   **Initial implementation:** **6 weeks.**
+*   **Documentation:** Write the user's guide and a codelab. **3 weeks.**
+*   **Company-wide roll-out:** Implement a process for promoting and tracking
+    adoption. **1 week.**
+*   **Customer support, incremental improvements, and maintenance:** **On-going
+    effort.**
+
+## Potential Patents
+
+We'll know whether there will be patentable inventions when we have a more
+concrete design and prototype. At that time, we should talk to Google's
+[patent counsel](mailto:patents@google.com).
+
+## Things that Don't Apply
+
+### Security Considerations
+
+This is an internal library for writing (unit) tests, and will not be used in
+production. Therefore there is no security concern.
+
+### Privacy Considerations
+
+gMock will not touch any user data. Therefore there is no concern about user
+privacy.
+
+### Standards
+
+There is no existing standard in creating C++ mocks.
+
+### Logging Plan
+
+This is an internal library and will not handle any user request. Therefore
+there is no plan for logging.
+
+### Monitoring Plan
+
+This is an internal library and will not run on our production servers.
+Therefore no monitoring is required.
+
+### Internationalization Plan
+
+gMock is not visible to external users, so there is no plan to internationalize
+it.
+
+### Billing Plan and Tax Plan
+
+gMock is an internal library and doesn't involve money, so there is no billing
+plan or tax plan.
+
+### Launch Plans
+
+gMock will not launch externally as a Google property. However, we may later
+decide to open source it.
+
+## References
+
+*   [jMock 1 cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/JMockOneCheatSheet) -
+    I compiled this from the downloaded jMock 1 source code.
+*   [jMock 1 JavaDoc](http://www.corp.google.com/~wan/jmock1/javadoc/) - I built
+    this locally. The one on http://jmock.org can be slow and may change.
+*   [jMock 2 cheat sheet](http://www.jmock.org/cheat-sheet.html) - as found on
+    http://jmock.org.
+*   [jMock 2 cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/JMockTwoCheatSheet) -
+    I compiled this from the jMock 2 source code in CVS as of 3/21.
+*   [jMock 2 JavaDoc](http://www.corp.google.com/~wan/jmock2/javadoc) - I
+    generated this locally from the jMock 2 source code in CVS as of 3/21. No
+    official jMock 2 JavaDoc is available yet, as the library hasn't been
+    released.
+*   [mockpp cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/MockppCheatSheet) -
+    I compiled this from the mockpp source code.
+*   [mockpp API docs](http://mockpp.sourceforge.net/api-doc/index.html) -
+    external.
+
+## Acknowledgments
+
+This design doc contains many ideas from PiotrKaminski. We'd also like to thank
+the following people for contributing ideas to this project:
+
+JoeWalnes, CraigSilverstein, JeffreyYasskin, KeithRay, MikeBland.
diff --git a/googlemock/docs/guide.md b/googlemock/docs/guide.md
new file mode 100644
index 00000000..3e745940
--- /dev/null
+++ b/googlemock/docs/guide.md
@@ -0,0 +1,49 @@
+# googletest gMock Users Guide
+
+go/gmockguide
+
+Welcome to googletest: Google's C++ testing and mocking framework. gMock is a
+mocking part of googletest.
+
+*   [OSS Version](https://github.com/google/googletest)
+*   [Google3](http://google3/third_party/googletest/)
+
+*   If you are new to gMock, start with [*gMock for Dummies*](for_dummies.md) to
+    learn the basic usage.
+
+*   Read [gMock Cookbook](cook_book.md) to learn more advanced usage and useful
+    tips.
+
+*   For a quick reference, check out [gMock Cheat Sheet](cheat_sheet.md).
+
+*   If you have questions, search [gMock FAQ](#GMockFaq) and the gmock-users@
+    archive before sending them to gmock-users@.
+
+<!-- GOOGLETEST_CM0035 DO NOT DELETE -->
+
+<!--#include file="for_dummies.md"-->
+
+#### Side Effects
+
+<!-- mdformat off(github rendering does not support multiline tables) -->
+| Matcher                            | Description                             |
+| :--------------------------------- | :-------------------------------------- |
+| `Assign(&variable, value)` | Assign `value` to variable. |
+| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. |
+| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. |
+| `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. |
+| `SetArgReferee<N>(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. |
+| `SetArgPointee<N>(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. |
+| `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0. |
+| `SetArrayArgument<N>(first, last)` | Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range. |
+| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. |
+| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. |
+<!-- mdformat on -->
+
+*   When compiling with exceptions in google3, it's not enough to specify
+    `-fexceptions` to copts in your cc_test target. That flag will not be
+    inherited by gmock, and various headers will be compiled both with and
+    without `-fexceptions` causing subtle bugs. Instead you must pass
+    `--copt=-fexceptions` to the blaze command so the flag gets passed to all
+    targets... but this is Google and we don't use exceptions so it shouldn't
+    really be an issue.
diff --git a/googlemock/docs/index.md b/googlemock/docs/index.md
new file mode 100644
index 00000000..cc73e83c
--- /dev/null
+++ b/googlemock/docs/index.md
@@ -0,0 +1,127 @@
+# googletest Home
+
+go/gmock
+
+Googletest is Google's C++ testing and mocking framework. Please note that there
+are legacy names you may encounter "gUnit" and "gMock" - these names are now
+merged into "googletest"
+
+<!-- GOOGLETEST_CM0035 DO NOT DELETE -->
+
+## Testimonials
+
+> "I'm really enjoying trying it, and it's amazing to me how far you've taken
+> this in C++. It's changed the way I program (and therefore changed my life ;),
+> and one of my teams has adopted it for all/most tests (and I'm working on the
+> other)." \
+> -- *Derek Thomson*, Google Mountain View
+
+<section></section>
+
+> "I started using mocks with EasyMock in Java a few years ago and found them
+> **invaluable** for making unit testing as painless and effective as possible.
+> I'm very glad (and amazed) to see you've managed to create something similar
+> for C++. It's making the transition much more pleasant." \
+> -- *David Harkness*, Google Mountain View
+
+<section></section>
+
+> "I #included `gmock.h` and lived to tell the tale... Kept me from having to
+> depend on `MockBigtable` thus far, which is **huge**." \
+> -- *Matthew Simmons*, Google NYC
+
+<section></section>
+
+> "I like the approach of `EXPECT_CALL` much more than EasyMock's mock modes
+> (record, replay). It's the best way to ensure the user will never forget to
+> verify the expectations: do it automatically!" \
+> -- *Tiago Silverira*, Google Brazil
+
+<section></section>
+
+> "It's by far the best mocking library for C++, by a long-shot." \
+> -- *Joe Walnes*, co-creator of jMock, Google London
+
+## Learning googletest mocking
+
+Please see the [*googletest Users Guide*](guide.md) for the combined gMock
+mocking documentation.
+
+## Resources for Users
+
+*   More docs:
+    *   [Interview with gMock's Creator](http://www.corp.google.com/eng/testing/codegreen/v10/gMock.htm)
+        on the
+        [Feb 2008](http://www.corp.google.com/eng/testing/codegreen/v10/index.htm)
+        issue of [Code Green](http://go/codegreen) - discusses gMock's history
+        and philosophy.
+    *   "Mockers of the (C++) world, delight!": TotT
+        [episode 66](http://big.corp.google.com/~jmcmaster/testing/2007/12/episode-68-mockers-of-c-world-delight.html) -
+        quick intro on gMock's benefits and usage
+    *   "Mock logs better than gold": TotT
+        [episode 76](http://big.corp.google.com/~jmcmaster/testing/2008/02/episode-76-mock-logs-better-than-gold_21.html) -
+        how to test LOGs using gMock
+    *   "Testing legacy code gently": TotT
+        [episode 84](http://big.corp.google.com/~jmcmaster/testing/2008/04/episode-84-testing-legacy-code-gently.html) -
+        using mock callbacks to test legacy code without a big refactoring
+    *   "Literate testing with matchers": TotT
+        [episode 135](http://big.corp.google.com/~jmcmaster/testing/2009/06/episode-135-literate-testing-with_08.html) -
+        using matchers to get readable test code and readable test messages
+    *   "Making a perfect matcher": TotT
+        [episode 139](http://big.corp.google.com/~jmcmaster/testing/2009/07/episode-139-making-perfect-matcher.html) -
+        defining custom matchers easily
+*   Talks
+    *   "Declarative C++ Testing Using DSLs" talk (6/4/2008):
+        [abstract](https://wiki.corp.google.com/twiki/bin/view/Main/WanTalks#Declarative_C_Testing_Using_DSLs),
+        [slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0806-declarative-cpp-testing.xul#Eva)
+        (requires Firefox) - gMock's design and implementation tricks
+    *   "Mocks made easy in C++ and Java" talk (4/23/2008):
+        [slides](http://go/MockTalk),
+        [fish](http://fish.corp.google.com/talks/8729/)
+    *   "C++ mocks made easy - an introduction to gMock" talk (1/22/2008)):
+        [slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0801-mv-gmock.xul#eva)
+        (requires Firefox),
+        [video](https://video.google.com/a/google.com/?AuthEventSource=SSO#/Play/contentId=bd07003d4193a646)
+    *   "A preview to gMock" talk (6/28/2007):
+        [PowerPoint slides](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0706-beijing-gmock-preview.ppt)
+*   Tools
+    *   `/google/src/head/depot/google3/third_party/googletest/googlemock/scripts/generator/gmock_gen.py
+        *your.h ClassNames*` generates mocks for the given base classes (if no
+        class name is given, all classes in the file are emitted).
+*   Mocks
+    *   [mock-log.h](http://s/?fileprint=//depot/google3/testing/base/public/mock-log.h) -
+        a sample on using gMock to create a mock class
+    *   [gmock-sample-mock-log.cc](http://s/?fileprint=//depot/google3/testing/base/internal/gmock-sample-mock-log.cc) -
+        a sample on using gMock to test LOG()s
+*   Folks
+    *   Meet the
+        [users](http://piano.kir.corp.google.com:8080/lica/?e=use%3Agmock).
+    *   `gmock-users` list:
+        [subscribe](https://groups.google.com/a/google.com/group/gmock-users/topics),
+        [archive](https://groups.google.com/a/google.com/group/gmock-users/topics),
+        [smile!](http://piano.kir.corp.google.com:8080/lica/?e=gmock-users) Send
+        questions here if you still need help after consulting the on-line docs.
+    *   `gmock-announce` list:
+        [subscribe](https://groups.google.com/a/google.com/group/gmock-announce/topics)
+        to this instead of `gmock-users` if you are interested in announcements
+        only.
+
+## Resources for Contributors
+
+*   [Dashboard](http://unittest.corp.google.com/project/gunit-gmock/)
+*   [*gMock Design*](design.md) (go/gmockdesign) - the design doc
+*   `c-mock-dev` list (deprecated) -
+    [old archive](https://mailman.corp.google.com/pipermail/c/c-mock-dev/),
+    [new archive](https://g.corp.google.com/group/c-mock-dev-archive)
+*   `opensource-gmock` list - discussions on the development of gMock:
+    [subscribe](https://groups.google.com/a/google.com/group/opensource-gmock/subscribe),
+    [archive](https://g.corp.google.com/group/opensource-gmock-archive),
+    [smile!](http://piano.kir.corp.google.com:8080/lica/?e=opensource-gmock)
+
+## Acknowledgments
+
+We'd like to thank the following people for their contribution to gMock: Piotr
+Kaminski, Jeffrey Yasskin (who/jyasskin), Joe Walnes, Bradford Cross, Keith Ray,
+Craig Silverstein, Matthew Simmons (who/simmonmt), Hal Burch (who/hburch), Russ
+Rufer, Rushabh Doshi (who/rdoshi), Gene Volovich (who/genev), Mike Bland, Neal
+Norwitz (who/nnorwitz), Mark Zuber, Vadim Berman (who/vadimb).
diff --git a/googlemock/docs/overview.md b/googlemock/docs/overview.md
new file mode 100644
index 00000000..0c77dfa7
--- /dev/null
+++ b/googlemock/docs/overview.md
@@ -0,0 +1,111 @@
+# GMock
+
+<!-- GOOGLETEST_CM0035 DO NOT DELETE -->
+
+## What is gMock?
+
+gMock is Google's framework for creating and using C++ mock classes. It helps
+you design better systems and write better tests. A mock object is an object
+that you use in a test instead of a real object. A mock object implements the
+same interface as a real object but lets you specify at run time how the object
+will be used. When you write tests that use a mock, you define expectations
+about how the mock's methods will be called. Your test then verifies how your
+real code behaves when interacting with the mock. See the
+[Mock Objects Best Practices Guide](http://go/mock-objects#mocks-stubs-fakes)
+for a comparison of mocks with stubs, fakes, and other kinds of test doubles.
+
+For example, gMock provides a simple syntax for declaring "I expect the
+RetryQuery method on this mock object to be called three times in the course of
+this test". Your test will fail if the expectation isn't met.
+
+The gMock library provides a mock framework for C++ similar to jMock or
+EasyMock[?](http://go/easymock-codelab) for Java. In gMock you use macros to
+define methods for your mock objects and set expectations for those methods.
+gMock runs on Linux, Windows, and Mac OS X.
+
+## What is gMock good for?
+
+Mocks in general are good for:
+
+-   prototyping and designing new code and APIs.
+-   removing unnecessary, expensive, or unreliable dependencies from your tests.
+
+gMock in particular is good for writing quality C++ mocks. Without the help of a
+mocking framework like gMock, good C++ mocks are hard to create.
+
+## What is gMock NOT good for?
+
+gMock is not good for testing the behavior of dependencies. The point of testing
+with mocks is to test the classes that use the mocks, not the mocks themselves.
+Objects that have working toy implementations are called fakes instead of mocks.
+For example, you could use an in-memory file system to fake disk operations.
+
+Mocks aren't useful for very simple classes like
+[Dumb Data Objects](http://big.corp.google.com/~jmcmaster/testing/2011/04/episode-220-blast-from-tott-past-dont.html).
+If it's more trouble to use a mock than the real class, just use the real class.
+
+## Who uses gMock?
+
+There are over 30K tests using gmock. Virtually every C++ test at Google that
+needs a mock object uses gMock.
+
+## Practical matters
+
+gMock is bundled with [gUnit](/third_party/googletest/googletest/docs/). To use
+gMock,
+[include a dependency](/third_party/googletest/googletest/docs/howto_cpp#LinuxTarget)
+on `//testing/base/public:gunit` in the BUILD rule for your mocks, and use the
+following include statement in the file that defines your mock class:
+
+```
+#include "gmock/gmock.h"
+```
+
+&nbsp;                      | &nbsp;
+--------------------------- | ------------------------------------------
+**Implementation language** | C++
+**Code location**           | google3/third_party/googletest/googlemock/
+**Build target**            | //testing/base/public:gunit
+
+## Best practices
+
+Use [dependency injection](http://en.wikipedia.org/wiki/Dependency_injection) to
+enable easy mocking. If you define dependencies as interfaces rather than
+concrete classes, you can swap out the production version of a class for a mock
+during testing.
+
+You can also use gMock during the design phase for your system. By sketching
+your architecture using mocks rather than full implementations, you can evolve
+your design more quickly.
+
+## History and evolution
+
+In January 2007 Zhanyong Wan and the Testing Technology team met with
+experienced C++ engineers to find out about C++ testing needs. The team learned
+that creating mocks in C++ was a major pain point. They looked around for
+existing frameworks but didn't find anything satisfactory. So Zhanyong Wan
+tackled the problem of creating a usable C++ mocking framework.
+
+C++ posed a unique problem for mocking: while
+[reflection](http://en.wikipedia.org/wiki/Reflection_\(computer_programming\))
+in Java and Python make it easy to generate a mock implementation of any
+interface, C++ does not have reflection. Wan hit on macros as a way to simplify
+mock writing in C++, and gMock was born.
+
+## Who to contact
+
+-   g/gmock-users
+-   g/gmock-announce
+
+## Additional resources
+
+-   [gMock](http://go/gmock) - homepage
+-   [GMock for Dummies](http://<!-- GOOGLETEST_CM0013 DO NOT DELETE -->) - gets you started with gMock
+    quickly
+-   [GMock Cookbook](http://<!-- GOOGLETEST_CM0012 DO NOT DELETE -->) - recipes for common scenarios; covers
+    advanced usage.
+-   [GMock Cheat Sheet](http://<!-- GOOGLETEST_CM0020 DO NOT DELETE -->) - a quick reference
+-   [GMock FAQ](http://<!-- GOOGLETEST_CM0021 DO NOT DELETE -->) - frequently asked questions
+-   [gUnit GDH page](http://go/gunit-overview)
+-   [gUnit User's Guide](http://goto.corp.google.com/gunit) - gets you started
+    with gUnit, which is closely related to gMock
diff --git a/googlemock/docs/sitemap.md b/googlemock/docs/sitemap.md
new file mode 100644
index 00000000..78f2d1fa
--- /dev/null
+++ b/googlemock/docs/sitemap.md
@@ -0,0 +1,11 @@
+Googletest Mocking (gMock)
+
+*   [Home](index.md)
+*   [Overview](overview.md)
+*   [User's Guide](guide.md)
+*   [gMock For Dummies](for_dummies.md)
+*   [gMock Cookbook](cook_book.md)
+*   [gMock Cheat Sheet](cheat_sheet.md)
+*   [Design](design.md)
+*   [How To Contribute](contribute.md)
+*   [gMock FAQ](gmock_faq.md)
diff --git a/googlemock/docs/under-construction-banner.md b/googlemock/docs/under-construction-banner.md
new file mode 100644
index 00000000..2ee59f93
--- /dev/null
+++ b/googlemock/docs/under-construction-banner.md
@@ -0,0 +1,4 @@
+**WARNING:** This document was recently migrated from
+[Goowiki](http://wtf/goowiki) (b/35424903) and may still require additional
+updates or formatting. You can still access the original document on Goowiki
+until the cleanup is complete: