Clean up callback interfaces.

service/datastore/interface.go

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 package datastore
 
 import (
         "golang.org/x/net/context"
 )
 
@@ skipping 78 matching lines @@
         //
         // Note that the behavior of transactions may change depending on what filters
         // have been installed. It's possible that we'll end up implementing things
         // like nested/buffered transactions as filters.
         RunInTransaction(f func(c context.Context) error, opts *TransactionOptions) error
 
         // Run executes the given query, and calls `cb` for each successfully
         // retrieved item.
         //
         // cb is a callback function whose signature is
-        //   func(obj TYPE, getCursor CursorCB) bool
+        //   func(obj TYPE[, getCursor CursorCB]) [error]
         //
         // Where TYPE is one of:
         //   - S or *S where S is a struct
         //   - P or *P where *P is a concrete type implementing PropertyLoadSaver
         //   - *Key (implies a keys-only query)
         //
-        // Run stops on the first error encountered.
+        // If the error is omitted from the signature, this will run until the query
+        // returns all its results, or has an error/times out.
+        //
+        // If error is in the signature, the query will continue as long as the
+        // callback returns nil. If it returns `Stop`, the query will stop and Run
+        // will return nil. Otherwise, the query will stop and Run will return the
+        // user's error.
+        //
+        // Run may also stop on the first datastore error encountered, which can occur
+        // due to flakiness, timeout, etc. If it encounters such an error, it will
+        // be returned.
         Run(q *Query, cb interface{}) error
 
         // Count executes the given query and returns the number of entries which
         // match it.
         Count(q *Query) (int64, error)
 
         // DecodeCursor converts a string returned by a Cursor into a Cursor instance.
         // It will return an error if the supplied string is not valid, or could not
         // be decoded by the implementation.
         DecodeCursor(string) (Cursor, error)
@@ skipping 66 matching lines @@
 
         // Testable returns the Testable interface for the implementation, or nil if
         // there is none.
         Testable() Testable
 
         // Raw returns the underlying RawInterface. The Interface and RawInterface may
         // be used interchangably; there's no danger of interleaving access to the
         // datastore via the two.
         Raw() RawInterface
 }