[datastore] improve docs around auto-generated *Keys on Put.

service/datastore/interface.go

 // Copyright 2015 The LUCI Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //      http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
@@ skipping 152 matching lines @@
 // KeyForObjErr extracts a key from src.
 //
 // src must be one of:
 //   - *S, where S is a struct
 //   - a PropertyLoadSaver
 //
 // It is expected that the struct exposes the following metadata (as retrieved
 // by MetaGetter.GetMeta):
 //   - "key" (type: Key) - The full datastore key to use. Must not be nil.
 //     OR
-//   - "id" (type: int64 or string) - The id of the Key to create
+//   - "id" (type: int64 or string) - The id of the Key to create.
 //   - "kind" (optional, type: string) - The kind of the Key to create. If
 //     blank or not present, KeyForObjErr will extract the name of the src
 //     object's type.
 //   - "parent" (optional, type: Key) - The parent key to use.
 //
 // By default, the metadata will be extracted from the struct and its tagged
 // properties. However, if the struct implements MetaGetterSetter it is
 // wholly responsible for exporting the required fields. A struct that
 // implements GetMeta to make some minor tweaks can evoke the defualt behavior
 // by using GetPLS(s).GetMeta.
@@ skipping 380 matching lines @@
 //
 // src must be one of:
 //      - *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.
 //
 // 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.
+// extractedKey.IsIncomplete() is true, then Put will write the resolved
+// (datastore-generated) *Key back to src.
+//
+// NOTE: The datastore only autogenerates *Keys with integer IDs. Only models
+// which use a raw `$key` or integer-typed `$id` field are elegible for this.
+// A model with a string-typed `$id` field will not accept an integer id'd *Key
+// and will cause the Put to fail.
 //
 // 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 a src argument is a slice, its error type will be a MultiError. Note
 // that in the scenario where multiple slices are provided, this will return a
 // MultiError containing a nested MultiError for each slice argument.
@@ skipping 119 matching lines @@
         }
         return err
 }
 
 func filterStop(err error) error {
         if err == Stop {
                 err = nil
         }
         return err
 }