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

service/datastore/key.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 232 matching lines @@
         for _, t := range k.toks {
                 if t.StringID != "" {
                         fmt.Fprintf(b, "/%s,%q", t.Kind, t.StringID)
                 } else {
                         fmt.Fprintf(b, "/%s,%d", t.Kind, t.IntID)
                 }
         }
         return b.String()
 }
 
-// IsIncomplete returns true iff k doesn't have an id yet.
+// IsIncomplete returns true iff the last token of this Key doesn't define
+// either a StringID or an IntID.
 func (k *Key) IsIncomplete() bool {
         return k.LastTok().IsIncomplete()
 }
 
 // Valid determines if a key is valid, according to a couple of rules:
 //   - k is not nil
 //   - every token of k:
 //     - (if !allowSpecial) token's kind doesn't start with '__'
 //     - token's kind and appid are non-blank
 //     - token is not incomplete
@@ skipping 266 matching lines @@
         for _, t := range k.toks {
                 ret += int64(len(t.Kind))
                 if t.StringID != "" {
                         ret += int64(len(t.StringID))
                 } else {
                         ret += 8
                 }
         }
         return ret
 }