update and clean up README

README.md

@@ -1,5 +1,5 @@
 # qstring
-The package provides an easy way to marshal and unmarshal query string data to
+This package provides an easy way to marshal and unmarshal url query string data to
 and from structs.
 
 ## Installation
@@ -9,7 +9,7 @@ $ go get github.com/dyninc/qstring
 
 ## Examples
 
-### Basic Unmarshal
+### Unmarshaling
 
 ```go
 package main
@@ -40,7 +40,7 @@ func handler(w http.ResponseWriter, req *http.Request) {
 
 The above example will unmarshal the query string from an http.Request and
 unmarshal it into the provided struct. This means that a query of
-`` would be unmarshaled into a struct similar
+`?names=foo&names=bar&limit=50&page=1` would be unmarshaled into a struct similar
 to the following:
 
 ```go
@@ -52,9 +52,9 @@ Query{
 ```
 
 ### Marshalling
-`qstring` exposes two methods of Marshaling structs into Query parameters, one
-will Marshal the provided struct into a raw query string, the other will Marshal
-a struct into a `url.Values` type. Some Examples of both follow.
+`qstring` also exposes two methods of Marshaling structs *into* Query parameters,
+one will Marshal the provided struct into a raw query string, the other will
+Marshal a struct into a `url.Values` type. Some Examples of both follow.
 
 ### Marshal Raw Query String
 ```go
@@ -80,7 +80,7 @@ func main() {
 		Limit: 50,
 		Page: 1,
 	}
-  q, err := qstring.Marshal(query)
+	q, err := qstring.Marshal(query)
 	fmt.Println(q)
   // Output: names=foo&names=bar&limit=50&page=1
 }
@@ -105,12 +105,12 @@ type Query struct {
 }
 
 func main() {
-  query := &Query{
+	query := &Query{
 		Names: []string{"foo", "bar"},
 		Limit: 50,
 		Page: 1,
 	}
-  q, err := qstring.MarshalValues(query)
+	q, err := qstring.MarshalValues(query)
 	fmt.Println(q)
   // Output: map[names:[foo, bar] limit:[50] page:[1]]
 }
@@ -131,22 +131,23 @@ import (
 
 // PagingParams represents common pagination information for query strings
 type PagingParams struct {
-  Page int
-  Limit int
+	Page int
+	Limit int
 }
 
 // Query is the http request query struct.
 type Query struct {
-  Names    []string
-  PageInfo PagingParams
+	Names    []string
+	PageInfo PagingParams
 }
 ```
 
 ## Additional Notes
 * All Timestamps are assumed to be in RFC3339 format
-* A struct field tag of `qstring` is supported and. This supports all of the
-functionality you've come to know and love. Ie a value of `"-"` instructs `qstring`
-to ignore the field.
+* A struct field tag of `qstring` is supported and supports all of the features
+you've come to know and love from Go (un)marshalers.
+  * A field tag with a value of `qstring:"-"` instructs `qstring` to ignore the field.
+  * A field tag with an the `omitempty` option set will be ignored `qstring:"name,omitempty"`
 
 ### Complex Structures
 Again, in the spirit of other Unmarshaling libraries, `qstring` allows for some
@@ -162,16 +163,24 @@ import (
 
 // PagingParams represents common pagination information for query strings
 type PagingParams struct {
-  Page int	`qstring:"page"`
-  Limit int `qstring:"limit"`
+	Page int	`qstring:"page"`
+	Limit int `qstring:"limit"`
 }
 
 // Query is the http request query struct.
 type Query struct {
-  Names    []string
-  IDs      []int
-  PageInfo *PagingParams
-  Created  time.Time
-  Modified time.Time
+	Names    []string
+	IDs      []int
+	PageInfo *PagingParams
+	Created  time.Time
+	Modified time.Time
 }
 ```
+
+### Custom Fields
+In order to facilitate more complex queries `qstring` also provides some custom
+fields to save you a bit of headache with custom marshal/unmarshaling logic.
+Currently the following custom fields are provided:
+
+* `qstring.ComparativeTime` - Supports timestamp query parameters with optional
+logical operators (<, >, <=, >=) such as `?created<=2006-01-02T15:04:05Z`