bencode/api.go    | 32 +++++++++++++++++++++++++-------
 bencode/decode.go |  2 +-

diff --git a/bencode/api.go b/bencode/api.go
index 28828d5ecaa197be293ab99a33abcfe346da018d..47f246420af8d5f2bfd2dc4babe2c33a2abfdbcc 100644
--- a/bencode/api.go
+++ b/bencode/api.go
@@ -10,9 +10,8 @@ //----------------------------------------------------------------------------
 // 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 @@ 	}
 	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 @@ 	return "bencode: key \"" + e.Key + "\" led to an unexported field \"" +
 		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 @@ 		strconv.FormatInt(e.Offset, 10) +
 		"): " + 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 @@ //----------------------------------------------------------------------------
 // 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 @@ 	}
 	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 72251e50910bf4a76bc6d6717e4bbf6b851a615b..e3324b4725483b67505ac63e97f193336962421e 100644
--- a/bencode/decode.go
+++ b/bencode/decode.go
@@ -389,7 +389,7 @@ 		if d.read_one_value() {
 			err := m.UnmarshalBencode(d.buf.Bytes())
 			d.buf.Reset()
 			if err != nil {
-				panic(err)
+				panic(&UnmarshalerError{v.Type(), err})
 			}
 			return true
 		}