From: nsf <no.smile.face@gmail.com>
Date: Sat, 30 Jun 2012 16:26:20 +0000 (+0600)
Subject: Add more comments to the bencode library. Implement UnmarshalerError.
X-Git-Tag: v1.0.0~1199^2~27
X-Git-Url: http://www.git.stargrave.org/?a=commitdiff_plain;h=d0429086bede41680a2f18d1c8b004caf63ded95;p=btrtrc.git

Add more comments to the bencode library. Implement UnmarshalerError.
---

diff --git a/bencode/api.go b/bencode/api.go
index 28828d5e..47f24642 100644
--- a/bencode/api.go
+++ b/bencode/api.go
@@ -10,9 +10,8 @@ import "io"
 // Errors
 //----------------------------------------------------------------------------
 
-// In case if marshaler cannot encode a type in bencode, it will return this
-// error. Typical example of such type is float32/float64 which has no bencode
-// representation
+// In case if marshaler cannot encode a type, it will return this error. Typical
+// example of such type is float32/float64 which has no bencode representation.
 type MarshalTypeError struct {
 	Type reflect.Type
 }
@@ -37,8 +36,7 @@ func (e *UnmarshalInvalidArgError) Error() string {
 	return "bencode: Unmarshal(nil " + e.Type.String() + ")"
 }
 
-// Unmarshaler spotted a value that was not appropriate for a given specific Go
-// value
+// Unmarshaler spotted a value that was not appropriate for a given Go value.
 type UnmarshalTypeError struct {
 	Value string
 	Type  reflect.Type
@@ -61,6 +59,7 @@ func (e *UnmarshalFieldError) Error() string {
 		e.Field.Name + "\" in type: " + e.Type.String()
 }
 
+// Malformed bencode input, unmarshaler failed to parse it.
 type SyntaxError struct {
 	Offset int64  // location of the error
 	what   string // error description
@@ -72,6 +71,8 @@ func (e *SyntaxError) Error() string {
 		"): " + e.what
 }
 
+// A non-nil error was returned after calling MarshalBencode on a type which
+// implements the Marshaler interface.
 type MarshalerError struct {
 	Type reflect.Type
 	Err  error
@@ -81,16 +82,29 @@ func (e *MarshalerError) Error() string {
 	return "bencode: error calling MarshalBencode for type " + e.Type.String() + ": " + e.Err.Error()
 }
 
+// A non-nil error was returned after calling UnmarshalBencode on a type which
+// implements the Unmarshaler interface.
+type UnmarshalerError struct {
+	Type reflect.Type
+	Err error
+}
+
+func (e *UnmarshalerError) Error() string {
+	return "bencode: error calling UnmarshalBencode for type " + e.Type.String() + ": " + e.Err.Error()
+}
+
 //----------------------------------------------------------------------------
 // Interfaces
 //----------------------------------------------------------------------------
 
-// unused for now (TODO)
+// Any type which implements this interface, will be marshaled using the
+// specified method.
 type Marshaler interface {
 	MarshalBencode() ([]byte, error)
 }
 
-// unused for now (TODO)
+// Any type which implements this interface, will be unmarshaled using the
+// specified method.
 type Unmarshaler interface {
 	UnmarshalBencode([]byte) error
 }
@@ -99,6 +113,8 @@ type Unmarshaler interface {
 // Stateless interface
 //----------------------------------------------------------------------------
 
+// Marshal the value 'v' to the bencode form, return the result as []byte and an
+// error if any.
 func Marshal(v interface{}) ([]byte, error) {
 	var buf bytes.Buffer
 	e := encoder{Writer: bufio.NewWriter(&buf)}
@@ -109,6 +125,8 @@ func Marshal(v interface{}) ([]byte, error) {
 	return buf.Bytes(), nil
 }
 
+// Unmarshal the bencode value in the 'data' to a value pointed by the 'v'
+// pointer, return a non-nil error if any.
 func Unmarshal(data []byte, v interface{}) error {
 	e := decoder{Reader: bufio.NewReader(bytes.NewBuffer(data))}
 	return e.decode(v)
diff --git a/bencode/decode.go b/bencode/decode.go
index 72251e50..e3324b47 100644
--- a/bencode/decode.go
+++ b/bencode/decode.go
@@ -389,7 +389,7 @@ func (d *decoder) parse_unmarshaler(v reflect.Value) bool {
 			err := m.UnmarshalBencode(d.buf.Bytes())
 			d.buf.Reset()
 			if err != nil {
-				panic(err)
+				panic(&UnmarshalerError{v.Type(), err})
 			}
 			return true
 		}