Fix example go program

Stephen Martinis · Commit Bot · commit 63e2e6604bc9 · 2018-02-21T00:42:18.000Z
Change-Id: If9343e981a39a4606b30bbc55465b6954b2a3fcc Reviewed-on: https://chromium-review.googlesource.com/924568 Reviewed-by: Robbie Iannucci <iannucci@chromium.org> Commit-Queue: Stephen Martinis <martiniss@chromium.org>
diff --git a/doc.go b/doc.go
@@ -47,60 +47,6 @@
 //   - filter/*    extra filter functionality for the services, agnostic to the
 //                 underlying implementation.
 //
-// TLDR
-//
-// In production, do:
-//
-//   import (
-//     "fmt"
-//     "net/http"
-//
-//     "go.chromium.org/gae/impl/prod"
-//     "go.chromium.org/gae/service/datastore"
-//     "golang.org/x/net/context"
-//   )
-//
-//   func handler(w http.ResponseWriter, r *http.Request) {
-//     c := prod.UseRequest(r)
-//     // add production filters, etc. here
-//     innerHandler(c, w)
-//   }
-//
-//   type CoolStruct struct {
-//     ID `gae:"$id"`
-//
-//     Value string
-//   }
-//
-//   func innerHandler(c context.Context, w http.ResponseWriter) {
-//     obj := &CoolStruct{Value: "hello"}
-//     if err := rds.Put(c, obj); err != nil {
-//       http.Error(w, err.String(), http.StatusInternalServerError)
-//     }
-//     fmt.Fprintf(w, "I wrote: %s", ds.KeyForObj(obj))
-//   }
-//
-// And in your test do:
-//
-//   import (
-//     "testing"
-//     "fmt"
-//     "net/http"
-//
-//     "go.chromium.org/gae/impl/memory"
-//     "go.chromium.org/gae/service/datastore"
-//     "golang.org/x/net/context"
-//   )
-//
-//   func TestHandler(t *testing.T) {
-//     t.Parallel()
-//     c := memory.Use(context.Background())
-//     // use datastore here to monkey with the database, install testing
-//     // filters like featureBreaker to test error conditions in innerHandler,
-//     // etc.
-//     innerHandler(c, ...)
-//   }
-//
 // Service Definitions
 //
 // A service defintion lives under the `service` subfolder, and defines the
@@ -167,30 +113,6 @@
 // which API method was called. They're useful to embed in filter or service
 // implementations as stubs while you're implementing the filter.
 //
-// Usage
-//
-// You will typically access one of the service interfaces in your code like:
-//   // This is the 'production' code
-//   func HTTPHandler(r *http.Request) {
-//     c := prod.Use(appengine.NewContext(r))
-//     CoolFunc(c)
-//   }
-//
-//   // This is the 'testing' code
-//   func TestCoolFunc(t *testing.T) {
-//     c := memory.Use(context.Background())
-//     CoolFunc(c)
-//   }
-//
-//   func CoolFunc(c context.Context, ...) {
-//     SomeOtherFunction(c, ...)
-//
-//     // because you might need to:
-//     ds.RunInTransaction(c, func (c context.Context) error {
-//       SomeOtherFunction(c, ...)  // c contains transactional versions of everything
-//     }, nil)
-//   }
-//
 // Filters
 //
 // Each service also supports "filters". Filters are proxy objects which have
diff --git a/example_test.go b/example_test.go
@@ -0,0 +1,62 @@
+// Copyright 2018 The LUCI Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package gae
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+
+	"go.chromium.org/gae/impl/memory"
+	"go.chromium.org/gae/impl/prod"
+	"go.chromium.org/gae/service/datastore"
+	"golang.org/x/net/context"
+)
+
+func Example() {
+	// This is suitable for use in tests.
+	c := memory.Use(context.Background())
+	w := httptest.NewRecorder()
+	_, err := http.NewRequest("GET", "/doesntmatter", nil)
+	if err != nil {
+		panic(err)
+	}
+
+	innerHandler(c, w)
+	fmt.Printf(string(w.Body.Bytes()))
+	// Output: I wrote: dev~app::/CoolStruct,"struct-id"
+}
+
+// This is what you would use in production.
+func handler(w http.ResponseWriter, r *http.Request) {
+	c := context.Background()
+	c = prod.Use(c, r)
+	// add production filters, etc. here
+	innerHandler(c, w)
+}
+
+type CoolStruct struct {
+	ID string `gae:"$id"`
+
+	Value string
+}
+
+func innerHandler(c context.Context, w http.ResponseWriter) {
+	obj := &CoolStruct{ID: "struct-id", Value: "hello"}
+	if err := datastore.Put(c, obj); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+	}
+	fmt.Fprintf(w, "I wrote: %s", datastore.KeyForObj(c, obj))
+}
diff --git a/service/datastore/errors.go b/service/datastore/errors.go
@@ -18,20 +18,23 @@ import (
 	"fmt"
 	"reflect"
 
-	"go.chromium.org/gae"
-
 	"go.chromium.org/luci/common/errors"
 
 	"google.golang.org/appengine/datastore"
 )
 
+type stopErr struct{}
+
+func (stopErr) Error() string { return "stop iteration" }
+
 // These errors are returned by various datastore.Interface methods.
 var (
 	ErrNoSuchEntity          = datastore.ErrNoSuchEntity
 	ErrConcurrentTransaction = datastore.ErrConcurrentTransaction
 
-	// Stop is an alias for "go.chromium.org/gae".Stop
-	Stop = gae.Stop
+	// Stop is understood by various services to stop iterative processes. Examples
+	// include datastore.Interface.Run's callback.
+	Stop = stopErr{}
 )
 
 // MakeErrInvalidKey returns an errors.Annotator instance that wraps an invalid
diff --git a/symbols.go b/symbols.go
