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 rawdatastore
+package datastore
 
 import (
         "errors"
         "fmt"
         "math"
         "reflect"
         "time"
 
         "github.com/luci/gae/service/blobstore"
 )
@@ skipping 308 matching lines @@
         // 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
 }