Merge pull request #334 from uber-go/v3-multidoc

Add comment discouraging MultiRead

client.go

@@ -164,6 +164,9 @@ type Client interface {
 	// Otherwise the DomainObject as key and an error message as value will be saved into
 	// MultiResult map.
 	// NOTE: This API only fetches objects of same entity type from same scope.
+	//
+	// Range should be preferred over MultiRead. If you are not sure which endpoint to use,
+	// use Range instead of MultiRead.
 	MultiRead(context.Context, []string, ...DomainObject) (MultiResult, error)
 
 	// Upsert creates or update a row. A list of fields to update can be
@@ -176,6 +179,9 @@ type Client interface {
 	// TODO: Coming in v2.1
 	// MultiUpsert creates or updates multiple rows. A list of fields to
 	// update can be specified. Use All() or nil for all fields.
+	//
+	// Upsert should be preferred over MultiUpsert. If you are not sure which endpoint to use,
+	// use Upsert instead of MultiUpsert.
 	// MultiUpsert(context.Context, []string, ...DomainObject) (MultiResult, error)
 
 	// Remove removes a row by primary key. The passed-in entity should contain