Refactor multiarg, split MGS/PLS.

service/datastore/interface.go

 // Copyright 2015 The LUCI Authors. All rights reserved.
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
 package datastore
 
 import (
         "golang.org/x/net/context"
 )
 
@@ skipping 119 matching lines @@
         // dst must be 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.
         GetAll(q *Query, dst interface{}) error
 
         // Exists tests if the supplied objects are present in the datastore.
         //
         // ent must be one of:
-        //      - *S where S is a struct
-        //      - *P where *P is a concrete type implementing PropertyLoadSaver
+        //      - *S, where S is a struct
+        //      - *P, where *P is a concrete type implementing PropertyLoadSaver
         //      - []S or []*S where S is a struct
         //      - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
         //      - []I where i is some interface type. Each element of the slice must
         //        be non-nil, and its underlying type must be either *S or *P.

[iannucci, 2016/06/14 00:19:51]

commas for these too?

[dnj (Google), 2016/06/14 01:49:43]

Done.

         //      - *Key, to check a specific key from the datastore.
         //      - []*Key, to check a slice of keys from the datastore.
         //
         // If an error is encountered, the returned error value will depend on the
         // input arguments. If one argument is supplied, the result will be the
         // encountered error type. If multiple arguments are supplied, the result will
         // be a MultiError whose error index corresponds to the argument in which the
         // error was encountered.
         //
         // If an ent argument is a slice, its error type will be a MultiError. Note
@@ skipping 46 matching lines @@
         // NOTE: GetMulti is obsolete. The vararg-accepting Get should be used
         // instead. This is left for backwards compatibility, but will be removed from
         // this interface at some point in the future.
         GetMulti(dst interface{}) error
 
         // Put inserts a single object into the datastore
         //
         // src must be one of:
         //      - *S where S is a struct
         //      - *P where *P is a concrete type implementing PropertyLoadSaver
+        //        IDs will NOT be written back.

[iannucci, 2016/06/14 00:19:51]

whoa why? Even if it implements MetaGetterSetter?

[dnj (Google), 2016/06/14 01:49:43]

oops, that's leftover from when they were structs.

         //      - []S or []*S where S is a struct
         //      - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
         //      - []I where i is some interface type. Each element of the slice must

[iannucci, 2016/06/14 00:19:51]

and everywhere

[dnj (Google), 2016/06/14 01:49:43]

Done.

         //        be non-nil, and its underlying type must be either *S or *P.
         //
         // A *Key will be extracted from src via KeyForObj. If
         // extractedKey.Incomplete() is true, then Put will write the resolved (i.e.
         // automatic datastore-populated) *Key back to src.
         //
         // If an error is encountered, the returned error value will depend on the
         // input arguments. If one argument is supplied, the result will be the
         // encountered error type. If multiple arguments are supplied, the result will
         // be a MultiError whose error index corresponds to the argument in which the
@@ skipping 16 matching lines @@
         // resolved keys back to the items in src.
         //
         // NOTE: PutMulti is obsolete. The vararg-accepting Put should be used
         // instead. This is left for backwards compatibility, but will be removed from
         // this interface at some point in the future.
         PutMulti(src interface{}) error
 
         // Delete removes the supplied entities from the datastore.
         //
         // ent must be one of:
-        //      - *S where S is a struct
-        //      - *P where *P is a concrete type implementing PropertyLoadSaver
+        //      - *S, where S is a struct
+        //      - *P, where *P is a concrete type implementing PropertyLoadSaver
         //      - []S or []*S where S is a struct
         //      - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
         //      - []I where i is some interface type. Each element of the slice must
         //        be non-nil, and its underlying type must be either *S or *P.
         //      - *Key, to remove a specific key from the datastore.
         //      - []*Key, to remove a slice of keys from the datastore.
         //
         // If an error is encountered, the returned error value will depend on the
         // input arguments. If one argument is supplied, the result will be the
         // encountered error type. If multiple arguments are supplied, the result will
@@ skipping 17 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
 }