Improve docs

service/rawdatastore/serialize.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
 
 import (
         "bytes"
         "errors"
         "fmt"
@@ skipping 133 matching lines @@
                 ret.IntID, _, err = cmpbin.ReadInt(buf)
                 if err == nil && ret.IntID <= 0 {
                         err = errors.New("helper: decoded key with empty stringID and zero/negative intID")
                 }
         default:
                 err = fmt.Errorf("helper: invalid type %s", PropertyType(typ))
         }
         return
 }
 
-// WriteGeoPoint writes a GeoPoint to the buffer.
-func WriteGeoPoint(buf Buffer, gp GeoPoint) (err error) {
+// Write writes a GeoPoint to the buffer.
+func (gp GeoPoint) Write(buf Buffer) (err error) {
         defer recoverTo(&err)
         _, e := cmpbin.WriteFloat64(buf, gp.Lat)
         panicIf(e)
         _, e = cmpbin.WriteFloat64(buf, gp.Lng)
         return e
 }
 
-// ReadGeoPoint reads a GeoPoint from the buffer.
-func ReadGeoPoint(buf Buffer) (gp GeoPoint, err error) {
+// Read reads a GeoPoint from the buffer.
+func (gp *GeoPoint) Read(buf Buffer) (err error) {
         defer recoverTo(&err)
         e := error(nil)
         gp.Lat, _, e = cmpbin.ReadFloat64(buf)
         panicIf(e)
 
         gp.Lng, _, e = cmpbin.ReadFloat64(buf)
         panicIf(e)
 
         if !gp.Valid() {
                 err = fmt.Errorf("helper: decoded invalid GeoPoint: %v", gp)
@@ skipping 16 matching lines @@
 
 // ReadTime reads a time.Time from the buffer.
 func ReadTime(buf Buffer) (time.Time, error) {
         v, _, err := cmpbin.ReadUint(buf)
         if err != nil {
                 return time.Time{}, err
         }
         return time.Unix(int64(v/1e6), int64((v%1e6)*1e3)).UTC(), nil
 }
 
-// WriteProperty writes a Property to the buffer. `context` behaves the same
+// Write writes a Property to the buffer. `context` behaves the same
 // way that it does for WriteKey, but only has an effect if `p` contains a
 // Key as its Value.
-func WriteProperty(buf Buffer, p Property, context KeyContext) (err error) {
+func (p *Property) Write(buf Buffer, context KeyContext) (err error) {
         defer recoverTo(&err)
         typb := byte(p.Type())
         if p.IndexSetting() == NoIndex {
                 typb |= 0x80
         }
         panicIf(buf.WriteByte(typb))
         switch p.Type() {
         case PTNull, PTBoolTrue, PTBoolFalse:
         case PTInt:
                 _, err = cmpbin.WriteInt(buf, p.Value().(int64))
         case PTFloat:
                 _, err = cmpbin.WriteFloat64(buf, p.Value().(float64))
         case PTString:
                 _, err = cmpbin.WriteString(buf, p.Value().(string))
         case PTBytes:
                 if p.IndexSetting() == NoIndex {
                         _, err = cmpbin.WriteBytes(buf, p.Value().([]byte))
                 } else {
                         _, err = cmpbin.WriteBytes(buf, p.Value().(ByteString))
                 }
         case PTTime:
                 err = WriteTime(buf, p.Value().(time.Time))
         case PTGeoPoint:
-                err = WriteGeoPoint(buf, p.Value().(GeoPoint))
+                err = p.Value().(GeoPoint).Write(buf)
         case PTKey:
                 err = WriteKey(buf, context, p.Value().(Key))
         case PTBlobKey:
                 _, err = cmpbin.WriteString(buf, string(p.Value().(blobstore.Key)))
         }
         return
 }
 
-// ReadProperty reads a Property from the buffer. `context`, `appid`, and
+// Read reads a Property from the buffer. `context`, `appid`, and
 // `namespace` behave the same way they do for ReadKey, but only have an
 // effect if the decoded property has a Key value.
-func ReadProperty(buf Buffer, context KeyContext, appid, namespace string) (p Property, err error) {
+func (p *Property) Read(buf Buffer, context KeyContext, appid, namespace string) (err error) {
         val := interface{}(nil)
         typb, err := buf.ReadByte()
         if err != nil {
                 return
         }
         is := ShouldIndex
         if (typb & 0x80) != 0 {
                 is = NoIndex
         }
         switch PropertyType(typb & 0x7f) {
@@ skipping 14 matching lines @@
                         break
                 }
                 if is == NoIndex {
                         val = b
                 } else {
                         val = ByteString(b)
                 }
         case PTTime:
                 val, err = ReadTime(buf)
         case PTGeoPoint:
-                val, err = ReadGeoPoint(buf)
+                gp := GeoPoint{}
+                err = gp.Read(buf)
+                val = gp
         case PTKey:
                 val, err = ReadKey(buf, context, appid, namespace)
         case PTBlobKey:
                 s := ""
                 if s, _, err = cmpbin.ReadString(buf); err != nil {
                         break
                 }
                 val = blobstore.Key(s)
         default:
                 err = fmt.Errorf("read: unknown type! %v", typb)
         }
         if err == nil {
                 err = p.SetValue(val, is)
         }
         return
 }
 
-// WritePropertyMap writes an entire PropertyMap to the buffer. `context`
+// Write writes an entire PropertyMap to the buffer. `context`
 // behaves the same way that it does for WriteKey. If
 // WritePropertyMapDeterministic is true, then the rows will be sorted by
 // property name before they're serialized to buf (mostly useful for testing,
 // but also potentially useful if you need to make a hash of the property data).
-func WritePropertyMap(buf Buffer, propMap PropertyMap, context KeyContext) (err error) {
+func (pm PropertyMap) Write(buf Buffer, context KeyContext) (err error) {
         defer recoverTo(&err)
-        rows := make(sort.StringSlice, 0, len(propMap))
+        rows := make(sort.StringSlice, 0, len(pm))
         tmpBuf := &bytes.Buffer{}
-        for name, vals := range propMap {
+        for name, vals := range pm {
                 tmpBuf.Reset()
                 _, e := cmpbin.WriteString(tmpBuf, name)
                 panicIf(e)
                 _, e = cmpbin.WriteUint(tmpBuf, uint64(len(vals)))
                 panicIf(e)
                 for _, p := range vals {
-                        panicIf(WriteProperty(tmpBuf, p, context))
+                        panicIf(p.Write(tmpBuf, context))
                 }
                 rows = append(rows, tmpBuf.String())
         }
 
         if WritePropertyMapDeterministic {
                 rows.Sort()
         }
 
-        _, e := cmpbin.WriteUint(buf, uint64(len(propMap)))
+        _, e := cmpbin.WriteUint(buf, uint64(len(pm)))
         panicIf(e)
         for _, r := range rows {
                 _, e := buf.WriteString(r)
                 panicIf(e)
         }
         return
 }
 
-// ReadPropertyMap reads a PropertyMap from the buffer. `context` and
+// Read reads a PropertyMap from the buffer. `context` and
 // friends behave the same way that they do for ReadKey.
-func ReadPropertyMap(buf Buffer, context KeyContext, appid, namespace string) (propMap PropertyMap, err error) {
+func (pm PropertyMap) Read(buf Buffer, context KeyContext, appid, namespace string) (err error) {
         defer recoverTo(&err)
 
         numRows := uint64(0)
         numRows, _, e := cmpbin.ReadUint(buf)
         panicIf(e)
         if numRows > ReadPropertyMapReasonableLimit {
                 err = fmt.Errorf("helper: tried to decode map with huge number of rows %d", numRows)
                 return
         }
 
         name, prop := "", Property{}
-        propMap = make(PropertyMap, numRows)
         for i := uint64(0); i < numRows; i++ {
                 name, _, e = cmpbin.ReadString(buf)
                 panicIf(e)
 
                 numProps, _, e := cmpbin.ReadUint(buf)
                 panicIf(e)
                 if numProps > ReadPropertyMapReasonableLimit {
                         err = fmt.Errorf("helper: tried to decode map with huge number of properties %d", numProps)
                         return
                 }
                 props := make([]Property, 0, numProps)
                 for j := uint64(0); j < numProps; j++ {
-                        prop, e = ReadProperty(buf, context, appid, namespace)
-                        panicIf(e)
+                        panicIf(prop.Read(buf, context, appid, namespace))
                         props = append(props, prop)
                 }
-                propMap[name] = props
+                pm[name] = props
         }
         return
 }
 
 type parseError error
 
 func panicIf(err error) {
         if err != nil {
                 panic(parseError(err))
         }
 }
 
 func recoverTo(err *error) {
         if r := recover(); r != nil {
                 if rerr := r.(parseError); rerr != nil {
                         *err = error(rerr)
                 }
         }
 }