add doc for package

Author: Stefan Tudose

README.md

@@ -1,8 +1,12 @@
 # csvdecoder
 
-csvdecoder is a Go library for parsing and decoding csv files into Go objects. It uses [encoding/csv](https://golang.org/pkg/encoding/csv/) for the parsing and follows a usage pattern inspired by the [database/sql](https://golang.org/pkg/database/sql/) package.
+csvdecoder is a Go library for parsing and deserializing csv files into Go objects.
+It relies on [encoding/csv](https://golang.org/pkg/encoding/csv/) for the actual parsing of the CSV file and follows a similar usage pattern as the [database/sql](https://golang.org/pkg/database/sql/) package for scanning rows.
+
+csvdecoder allows to iterate through the CSV records (using 'Next') and scan the fields into target variables or fields of variables (using 'Scan').
+
+The scanning method is **not thread safe**; `Next` and `Scan` are not expected to be called concurrently.
 
-The scanning method is *not multi-thread safe*; `Next` and `Scan` are not expected to be called concurrently.
 ## Installation
 
 ```bash
@@ -84,19 +88,21 @@ See also the example files for more usage examples.
 
 ## Configuration
 
-The behaviour of the decoder can be configured by passing one of following options when creating the decoder:
+The behavior of the decoder can be configured by passing one of following options when creating the decoder:
 - Comma: the character that separates values. Default value is comma.
-- IgnoreHeaders: if set to true, the first line will be ignored
+- IgnoreHeaders: if set to true, the first line will be ignored. This is useful when the CSV file contains a header line.
 - IgnoreUnmatchingFields: if set to true, the number of records and scan targets are allowed to be different. By default, if they don't match exactly it will cause an error.
 
 ```golang
 	decoder, err := csvdecoder.NewWithConfig(file, csvdecoder.Config{Comma: ';', IgnoreHeaders: true})
 ```
 
 ## Contributing
+
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 
 Please make sure to update tests as needed.
 
 ## License
+
 [MIT](https://choosealicense.com/licenses/mit/)

doc.go

@@ -0,0 +1,32 @@
+// csvdecoder is a tool for parsing and deserializing CSV values into Go objects.
+// It follows the same usage pattern as the Rows scanning using database/sql package.
+// It relies on encoding/csv for the actual csv parsing.
+
+// csvdecoder allows to iterate through the CSV records (using 'Next')
+// and scan the fields into target variables or fields of variables (using 'Scan').
+// The 'Next' and 'Scan' methods are not thread-safe and are not expected to be called concurrently.
+
+// csvdecoder supports converting CSV fields into any of the following types:
+// - `*string`
+// - `*int`, `*int8`, `*int16`, `*int32`, `*int64`
+// - `*uint`, `*uint8`, `*uint16`, `*uint32`, `*uint64`
+// - `*bool`
+// - `*float32`, `*float64`
+// - a slice of values. Note that the CSV record must be a valid JSON array. If not a JSON array, a custom decoder implementing the `csvdecoder.Interface` interface must be implemented.
+// - an array of values. Note that the CSV record must be a valid JSON array. If not a JSON array, a custom decoder implementing the `csvdecoder.Interface` interface must be implemented.
+// - a pointer to any type implementing the `csvdecoder.Interface` interface
+
+// csvdecoder uses the same terminology as package encoding/csv:
+// A csv file contains zero or more records. Each record contains one or more
+// fields separated by the fields separator (the "comma"). The fields separator character
+// can be configured to be another character than comma.
+// Each record is separated by the newline character. The final record may
+// optionally be followed by a newline character.
+
+// The behavior of the decoder can be configured by passing one of following options when creating the decoder:
+// - Comma: the character that separates values. The default value is comma.
+// - IgnoreHeaders: if set to true, the first line will be ignored. This is useful when the CSV file contains a header line.
+// - IgnoreUnmatchingFields: if set to true, the number of records and scan targets are allowed to be different. By default, if they don't match exactly it will cause an error.
+
+// See README.md for more info.
+package csvdecoder