Add 'user friendly' datastore API.

service/datastore/properties.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 datastore
 
 import (
         "errors"
         "fmt"
         "math"
@@ skipping 52 matching lines @@
 // handle the error normally, use SetValue(..., NoIndex) instead.
 func MkPropertyNI(val interface{}) Property {
         ret := Property{}
         if err := ret.SetValue(val, NoIndex); err != nil {
                 panic(err)
         }
         return ret
 }
 
 // PropertyConverter may be implemented by the pointer-to a struct field which
-// is serialized by datastore. Its ToProperty will be called on save, and
-// it's FromProperty will be called on load (from datastore). The method may
-// do arbitrary computation, and if it encounters an error, may return it.  This
-// error will be a fatal error (as defined by PropertyLoadSaver) for the
-// struct conversion.
+// is serialized by the struct PropertyLoadSaver from GetPLS. Its ToProperty
+// will be called on save, and it's FromProperty will be called on load (from
+// datastore). The method may do arbitrary computation, and if it encounters an
+// error, may return it.  This error will be a fatal error (as defined by
+// PropertyLoadSaver) for the struct conversion.
 //
 // Example:
 //   type Complex complex
 //   func (c *Complex) ToProperty() (ret Property, err error) {
 //     // something like:
 //     err = ret.SetValue(fmt.Sprint(*c), true)
 //     return
 //   }
 //   func (c *Complex) FromProperty(p Property) (err error) {
 //     ... load *c from p ...
@@ skipping 219 matching lines @@
         }
         p.propType = pt
         p.value = value
         p.indexSetting = is
         if t == typeOfByteSlice {
                 p.indexSetting = NoIndex
         }
         return
 }
 
-// PropertyLoadSaver may be implemented by a user type, and datastore will
+// PropertyLoadSaver may be implemented by a user type, and Interface will
 // use this interface to serialize the type instead of trying to automatically
 // create a serialization codec for it with helper.GetPLS.
 type PropertyLoadSaver interface {
         // Load takes the values from the given map and attempts to save them into
         // the underlying object (usually a struct or a PropertyMap). If a fatal
         // error occurs, it's returned via error. If non-fatal conversion errors
         // occur, error will be a MultiError containing one or more ErrFieldMismatch
         // objects.
         Load(PropertyMap) error
 
         // Save returns the current property as a PropertyMap. if withMeta is true,
         // then the PropertyMap contains all the metadata (e.g. '$meta' fields)
         // which was held by this PropertyLoadSaver.
         Save(withMeta bool) (PropertyMap, error)
 
         // GetMeta will get information about the field which has the struct tag in
-        // the form of `gae:"$<key>[,<value>]?"`.
+        // the form of `gae:"$<key>[,<default>]?"`.
         //
-        // string and int64 fields will return the <value> in the struct tag,
-        // converted to the appropriate type, if the field has the zero value.
+        // Supported metadata types are:
+        //   int64  - may have default (ascii encoded base-10)
+        //   string - may have default
+        //   Toggle - MUST have default ("true" or "false")
+        //   Key    - NO default allowed
         //
+        // Struct fields of type Toggle (which is an Auto/On/Off) require you to
+        // specify a value of 'true' or 'false' for the default value of the struct
+        // tag, and GetMeta will return the combined value as a regular boolean true
+        // or false value.
         // Example:
         //   type MyStruct struct {
         //     CoolField int64 `gae:"$id,1"`
         //   }
         //   val, err := helper.GetPLS(&MyStruct{}).GetMeta("id")
         //   // val == 1
         //   // err == nil
         //
         //   val, err := helper.GetPLS(&MyStruct{10}).GetMeta("id")
         //   // val == 10
         //   // err == nil
         //
-        // Struct fields of type Toggle (which is an Auto/On/Off) allow you to
-        // specify a value of 'true' or 'false' for the default value of the struct
-        // tag, and GetMeta will return the combined value as a regular boolean true
-        // or false value. If a field is Toggle, a <value> MUST be specified.
-        //
-        // Example:
         //   type MyStruct struct {
         //     TFlag Toggle `gae:"$flag1,true"`  // defaults to true
         //     FFlag Toggle `gae:"$flag2,false"` // defaults to false
         //     // BadFlag  Toggle `gae:"$flag3"` // ILLEGAL
         //   }
         GetMeta(key string) (interface{}, error)
 
         // SetMeta allows you to set the current value of the meta-keyed field.
         SetMeta(key string, val interface{}) error
 
@@ skipping 75 matching lines @@
                 return err
         }
         pm["$"+key] = []Property{prop}
         return nil
 }
 
 // Problem implements PropertyLoadSaver.Problem. It ALWAYS returns nil.
 func (pm PropertyMap) Problem() error {
         return nil
 }