Make the rest of the services have a similar raw/user interface structure.

service/memcache/interface.go

Index: service/memcache/interface.go
diff --git a/service/memcache/interface.go b/service/memcache/interface.go
index 346155b42e8b2c5fff93b8027a88f811573592cd..83e6035e4ab443144c914eb1d3baf6624ab40df0 100644
--- a/service/memcache/interface.go
+++ b/service/memcache/interface.go
@@ -6,24 +6,61 @@ package memcache
 
 // Interface is the full interface to the memcache service.

[dnj, 2015/08/03 22:37:25]

Document when MultiError instances will be returned.

[iannucci, 2015/08/04 01:21:21]

Done.

 type Interface interface {
+	// NewItem creates a new, mutable, memcache item.
 	NewItem(key string) Item
 
+	// Add puts a single item into memcache, but only if it didn't exist in
+	// memcache before.
 	Add(item Item) error
+
+	// Set the item in memcache, whether or not it exists.
 	Set(item Item) error
-	Get(key string) (Item, error)
+
+	// Get retrieves an item from memcache. Only the key field is read. The item
+	// will be mutated to contain the data in the memcache item.
+	Get(item Item) error
+
+	// Delete removes an item from memcache.
 	Delete(key string) error
+
+	// CompareAndSwap accepts an item which is the result of Get() or GetMulti().
+	// The Get functions add a secret field to item ('CasID'), which is used as
+	// the "compare" value for the "CompareAndSwap". The actual "Value" field of
+	// the object set by the Get functions is the "swap" value.
+	//
+	// Example:
+	//   mc := memcache.Get(context)
+	//   itm := mc.NewItem("aKey")
+	//   mc.Get(itm) // check error
+	//   itm.SetValue(append(itm.Value(), []byte("more bytes")))
+	//   mc.CompareAndSwap(itm) // check error
 	CompareAndSwap(item Item) error
 
 	AddMulti(items []Item) error

[dnj, 2015/08/03 22:37:25]

Exported methods need comments.

[iannucci, 2015/08/04 01:21:21]

Not on an interface, and if the reader can't figure out that these are related
to the documented ones then they probably shouldn't be using the library.

[dnj (Google), 2015/08/04 03:48:03]

http://fxr.watson.org/fxr/ident?im=3;i=EDOOFUS

 	SetMulti(items []Item) error
-	GetMulti(keys []string) (map[string]Item, error)
+	GetMulti(items []Item) error
 	DeleteMulti(keys []string) error
 	CompareAndSwapMulti(items []Item) error
 
+	// Increment adds delta to the uint64 contained at key. If the memcache key
+	// is missing, it's populated with initialValue before applying delta (i.e.
+	// the final value would be initialValue+delta).
+	//
+	// Underflow caps at 0, overflow wraps back to 0.
+	//
+	// If key contains a value which is not exactly 8 bytes, it's assumed to
+	// contain non-number data and this method will return an error.
 	Increment(key string, delta int64, initialValue uint64) (newValue uint64, err error)
+
+	// IncrementExisting is like Increment, except that the valu must exist
+	// already.
 	IncrementExisting(key string, delta int64) (newValue uint64, err error)
 
+	// Flush dumps the entire memcache state.
 	Flush() error
 
+	// Stats gets some best-effort statistics about the current state of memcache.
 	Stats() (*Statistics, error)
+
+	Raw() RawInterface
 }