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

doc.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 gae provides a fakable wrapped interface for the appengine SDK's
 // APIs. This means that it's possible to mock all of the supported appengine
 // APIs for testing (or potentially implement a different backend for them).
 //
 // Features
 //
@@ skipping 85 matching lines @@
 //
 // A service defintion lives under the `service` subfolder, and defines the
 // user-facing interface for a service. Each service has a few common types and
 // functions. Common types are:
 //
 //    service.Interface    - the main user-friendly service interface.
 //
 //    service.RawInterface - the internal service interface used by service
 //                           and filter implementations. Note that some services
 //                           like Info don't distinguish between the service
-//                           interface and the user interface.
+//                           interface and the user interface. This interface is
+//                           typically a bit lower level than Interface and
+//                           lacks convenience methods.
 //
 //    service.Testable     - any additional methods that a 'testing'
 //                           implementation should provide. It's expected that
 //                           tests will cast the RawInterface from GetRaw() to
 //                           Testable in order to access these methods.
 //
 //    service.RawFactory   - a function returning a RawInterface
 //
 //    service.RawFilter    - a function returning a new RawInterface based on
 //                           the previous filtered interface. Filters chain
 //                           together to allow behavioral service features
 //                           without needing to agument the underlying service
 //                           implementations directly.
 //
 // And common functions are:
 //    service.Get           - Retrieve the current, filtered Interface
 //                            implementation from the context. This is the most
 //                            frequently used service function by far.
 //
 //    service.GetRaw        - Retrieve the current, filtered RawInterface
 //                            implementation from the context. This is less
 //                            frequently used, but can be useful if you want to
 //                            avoid some of the overhead of the user-friendly
 //                            Interface, which can do sometimes-unnecessary amounts
 //                            of reflection or allocation. The RawInterface and
 //                            Interface for a service are fully interchangable and
 //                            usage of them can be freely mixed in an application.
 //
-//    service.AddRawFilters - adds one or more Filters to the context.
+//    service.AddRawFilters - adds one or more RawFilters to the context.
 //
-//    service.SetRawFactory - adds a Factory to the context
+//    service.SetRawFactory - adds a RawFactory to the context
 //
 //    service.SetRaw        - adds an implementation of RawInterface to the context
 //                            (shorthand for SetRawFactory, useful for testing)
 //
 // Implementations
 //
 // The impl subdirectory contains a couple different service implementations,
 // depending on your needs.
 //
 // 'prod' is the production (e.g. real appengine-backed) implementation. It
@@ skipping 65 matching lines @@
 // and the state can be observed to see how many times each API was invoked.
 // Since filters stack, we can compare counts from rawCount versus userCount to
 // see how many calls to the actual real datastore went through, vs. how many
 // went to memcache, for example.
 //
 // Note that Filters apply only to the service.RawInterface. All implementations
 // of service.Interface boil down to calls to service.RawInterface methods, but
 // it's possible that bad calls to the service.Interface methods could return
 // an error before ever reaching the filters or service implementation.
 package gae