Add example for Call.Do and Call.DoAndReturn

fixes issue #469
* include example of DoAndReturn in readme

Author: cvgw

README.md

@@ -167,11 +167,15 @@ func TestFoo(t *testing.T) {
 
   m := NewMockFoo(ctrl)
 
-  // Does not make any assertions. Returns 101 when Bar is invoked with 99.
+  // Does not make any assertions. Executes the anonymous functions and returns
+  // its result when Bar is invoked with 99.
   m.
     EXPECT().
     Bar(gomock.Eq(99)).
-    Return(101).
+    DoAndReturn(func(_ int) int {
+      time.Sleep(1*time.Second)
+      return 101
+    }).
     AnyTimes()
 
   // Does not make any assertions. Returns 103 when Bar is invoked with 101.

gomock/doc_test.go

@@ -0,0 +1,66 @@
+package gomock_test
+
+import (
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/golang/mock/gomock"
+	mock_sample "github.com/golang/mock/sample/mock_user"
+)
+
+func ExampleCall_DoAndReturn() {
+	t := &testing.T{} // provided by test
+	ctrl := gomock.NewController(t)
+	mockIndex := mock_sample.NewMockIndex(ctrl)
+
+	mockIndex.EXPECT().Get(gomock.Any()).DoAndReturn(
+		func() string {
+			time.Sleep(1 * time.Second)
+			return "I'm sleepy"
+		},
+	)
+}
+
+func ExampleCall_DoAndReturn_captureArguments() {
+	t := &testing.T{} // provided by test
+	ctrl := gomock.NewController(t)
+	mockIndex := mock_sample.NewMockIndex(ctrl)
+	var s string
+
+	mockIndex.EXPECT().Get(gomock.AssignableToTypeOf(s)).DoAndReturn(
+		// When capturing arguments the anonymous function should have the same signature as the mocked method.
+		func(arg string) interface{} {
+			time.Sleep(1 * time.Second)
+			fmt.Println(arg)
+			return "I'm sleepy"
+		},
+	)
+}
+
+func ExampleCall_Do() {
+	t := &testing.T{} // provided by test
+	ctrl := gomock.NewController(t)
+	mockIndex := mock_sample.NewMockIndex(ctrl)
+
+	mockIndex.EXPECT().Anon(gomock.Any()).Do(
+		func() {
+			time.Sleep(1 * time.Second)
+		},
+	)
+}
+
+func ExampleCall_Do_captureArguments() {
+	t := &testing.T{} // provided by test
+	ctrl := gomock.NewController(t)
+	mockIndex := mock_sample.NewMockIndex(ctrl)
+
+	var s string
+	mockIndex.EXPECT().Anon(gomock.AssignableToTypeOf(s)).Do(
+		// When capturing arguments the anonymous function should have the same signature as the mocked method.
+		func(arg string) {
+			time.Sleep(1 * time.Second)
+			fmt.Println(arg)
+		},
+	)
+}