Update documentation

decoder.go

@@ -32,6 +32,9 @@ type Decoder struct {
 // If header is empty NewDecoder will read one line and treat it as a header.
 //
 // Records coming from r must be of the same length as the header.
+//
+// NewDecoder may return io.EOF if there is no data in r and no header was
+// provided by the caller.
 func NewDecoder(r Reader, header ...string) (dec *Decoder, err error) {
 	if len(header) == 0 {
 		header, err = r.Read()
@@ -91,7 +94,7 @@ func NewDecoder(r Reader, header ...string) (dec *Decoder, err error) {
 // must implement csvutil.Unmarshaler or encoding.TextUnmarshaler.
 //
 // Anonymous struct fields without tags are populated just as if they were
-// part of the main struct. However fields in the main struct have bigger
+// part of the main struct. However, fields in the main struct have bigger
 // priority and they are populated first. If main struct and anonymous struct
 // field have the same fields, the main struct's fields will be populated.
 func (d *Decoder) Decode(v interface{}) (err error) {

doc.go

@@ -1,9 +1,2 @@
-// Package csvutil decodes string records to struct types.
-//
-// A string record, such as CSV, is held in []string type. Reader interface
-// defined in this package can read such records. The example implementation
-// that satisfies this interface is: csv.Reader.
-//
-// Decoder uses Reader to read new records and unmarshal them into the given
-// struct type.
+// Package csvutil provides decoding utilities for csv encoded data.
 package csvutil

error.go

@@ -52,6 +52,8 @@ func (e *InvalidDecodeError) Error() string {
 	return "csvutil: Decode(nil " + e.Type.String() + ")"
 }
 
+// An InvalidUnmarshalError describes an invalid argument passed to Unmarshal.
+// (The argument to Unmarshal must be a non-nil slice pointer.)
 type InvalidUnmarshalError struct {
 	Type reflect.Type
 }

example_decoder_test.go

@@ -10,7 +10,7 @@ import (
 	"github.com/jszwec/csvutil"
 )
 
-func ExampleDecoder_decodeCSV() {
+func ExampleDecoder_decode() {
 	type User struct {
 		ID   *int   `csv:"id,omitempty"`
 		Name string `csv:"name"`

example_decoder_unmashaler_test.go

@@ -1,12 +1,8 @@
 package csvutil_test
 
 import (
-	"encoding/csv"
 	"fmt"
-	"io"
-	"log"
 	"strconv"
-	"strings"
 
 	"github.com/jszwec/csvutil"
 )
@@ -20,30 +16,22 @@ func (b *Bar) UnmarshalCSV(s string) error {
 }
 
 type Foo struct {
+	Int int `csv:"int"`
 	Bar Bar `csv:"bar"`
 }
 
-func ExampleDecoder_unmarshaler() {
-	csvReader := csv.NewReader(strings.NewReader("10\n5"))
-
-	dec, err := csvutil.NewDecoder(csvReader, "bar")
-	if err != nil {
-		log.Fatal(err)
-	}
+func ExampleDecoder_customUnmarshalCSV() {
+	var csvInput = []byte(`int,bar
+5,10
+6,11`)
 
 	var foos []Foo
-	for {
-		var f Foo
-		if err := dec.Decode(&f); err == io.EOF {
-			break
-		} else if err != nil {
-			log.Fatal(err)
-		}
-		foos = append(foos, f)
+	if err := csvutil.Unmarshal(csvInput, &foos); err != nil {
+		fmt.Println("error:", err)
 	}
 
-	fmt.Println(foos)
+	fmt.Printf("%+v", foos)
 
 	// Output:
-	// [{10} {5}]
+	// [{Int:5 Bar:10} {Int:6 Bar:11}]
 }

example_unmarshal_test.go

@@ -0,0 +1,27 @@
+package csvutil_test
+
+import (
+	"fmt"
+
+	"github.com/jszwec/csvutil"
+)
+
+func ExampleDecoder_unmarshal() {
+	var csvInput = []byte(`name,age
+jacek,26
+john,27`)
+
+	type User struct {
+		Name string `csv:"name"`
+		Age  int    `csv:"age"`
+	}
+
+	var users []User
+	if err := csvutil.Unmarshal(csvInput, &users); err != nil {
+		fmt.Println("error:", err)
+	}
+	fmt.Printf("%+v", users)
+
+	// Output:
+	// [{Name:jacek Age:26} {Name:john Age:27}]
+}

interface.go

@@ -1,8 +1,8 @@
 package csvutil
 
-// Reader provides the interface for reading a single record.
+// Reader provides the interface for reading a single CSV record.
 //
-// If there is no data left to be read, Read returns nil, io.EOF.
+// If there is no data left to be read, Read returns (nil, io.EOF).
 //
 // It is implemented by csv.Reader.
 type Reader interface {