Merge pull request #20 from suzuki-shunsuke/docs/update-godoc

docs: update GoDoc

README.md

@@ -9,7 +9,7 @@
 
 Go library to check if two values are equal as data format such as JSON.
 
-This is inspired to [go-jsoneq](https://github.com/suzuki-shunsuke/go-jsoneq), and provides a general interface to support various data formats (ex. YAML).
+This is inspired to [go-jsoneq](https://github.com/suzuki-shunsuke/go-jsoneq), and provides a general API to support various data formats (ex. YAML).
 
 ## Example
 

dataeq/dataeq.go

@@ -5,22 +5,30 @@ import (
 )
 
 type (
-	Marshal   func(interface{}) ([]byte, error)
+	// Marshal converts data to a byte string.
+	Marshal func(interface{}) ([]byte, error)
+	// Unmarshal parses the encoded byte string and stores the result in the value pointed to by 2th argument.
+	// The 2th argument must be a pointer.
 	Unmarshal func([]byte, interface{}) error
 
+	// DataFormat allows to compare values as the data format.
+	// DataFormat must be created by the function `New`.
 	DataFormat struct {
 		marshal   func(interface{}) ([]byte, error)
 		unmarshal func([]byte, interface{}) error
 	}
 )
 
+// New creates DataFormat by Marshal and Unmarshal.
+// DataFormat must be created by this function.
 func New(marshal Marshal, unmarshal Unmarshal) DataFormat {
 	return DataFormat{
 		marshal:   marshal,
 		unmarshal: unmarshal,
 	}
 }
 
+// ConvertByte unmarshals a byte string to `interface{}`.
 func (df DataFormat) ConvertByte(b []byte) (interface{}, error) {
 	var d interface{}
 	err := df.unmarshal(b, &d)
@@ -30,6 +38,8 @@ func (df DataFormat) ConvertByte(b []byte) (interface{}, error) {
 	return nil, err
 }
 
+// Convert converts value to byte string and unmarshals the byte string to `interface{}`.
+// Convert can be used to normalize the value to compare with the other value.
 func (df DataFormat) Convert(x interface{}) (interface{}, error) {
 	if a, ok := x.([]byte); ok {
 		return df.ConvertByte(a)
@@ -41,6 +51,7 @@ func (df DataFormat) Convert(x interface{}) (interface{}, error) {
 	return df.ConvertByte(b)
 }
 
+// Equal returns true if two arguments are equal.
 func (df DataFormat) Equal(x, y interface{}) (bool, error) {
 	if reflect.DeepEqual(x, y) {
 		return true, nil

dataeq/doc.go

@@ -1,2 +1,9 @@
-// Package dataeq checks if two values are equal.
+// Package dataeq allows to create API to compare two values as the data format such as JSON and YAML.
+// dataeq compare two values by the followin way.
+//
+// 1. convert value to a byte string by Marshal
+// 2. unmarshal a byte string to `interface{}` by Unmarshal
+// 3. compare two values by reflect.DeepEqual
+//
+// So dataeq requires two API for the data format, Marhsal and Unmarshal.
 package dataeq