more docs including package desc for godoc

README.md

@@ -61,7 +61,9 @@ structs like those that jsonapi sends because it is very hard to get at all of
 your data easily.
 
 
-## Tags Example
+## Tags
+
+### Example
 
 You want jsonapi.org style inputs and ouputs but you want to keep your
 structs that you already have.  Use the jsonapi lib with the "jsonapi"
@@ -95,7 +97,43 @@ type Comment struct {
 }
 ```
 
-## Handler Examples
+### Reference
+
+The **jsonapi** Tag Reference
+
+#### `primary`
+
+```
+`jsonapi:"primary,<type field output>"`
+```
+
+This indicates that this is the primary key field for this struct type. Tag
+value arguments are comma separated.  The first argument must be, `primary`, and
+the second must be the name that should appear in the `type` field for all data
+objects that represent this type of model.
+
+#### `attr`
+
+```
+`jsonapi:"attr,<key name in attributes hash>"`
+```
+
+These fields' values should end up in the `attributes`hash for a record.  The first
+argument must be, `attr`, and the second should be the name for the key to display in
+the the `attributes` hash for that record.
+
+#### `relation`
+
+```
+`jsonapi:"relation,<key name in relationships hash>"`
+```
+
+Relations are struct fields that represent a one-to-one or one-to-many to other structs.
+jsonapi will traverse the graph of relationships and marshal or unmarshal records.  The first
+argument must be, `relation`, and the second should be the name of the relationship, used as
+the key in the `relationships` hash for the record.
+
+## Methods Reference
 
 **All `Marshal` and `Unmarshal` methods expect pointers to struct
 instance or slices of the same contained with the `interface{}`s**
@@ -103,7 +141,7 @@ instance or slices of the same contained with the `interface{}`s**
 Now you have your structs are prepared to be seralized or materialized.
 What about the rest?
 
-### Create
+### Create Record Example
 
 You can Unmarshal a jsonapi payload using `jsonapi.UnmarshalPayload`; convert an io
 into a struct instance using jsonapi tags on struct fields.  Method supports single
@@ -129,7 +167,7 @@ This method encodes a response for a single record only. If you want to serializ
 records, see, [MarshalManyPayload](#marshalmanypayload). Wrties a jsonapi response, with
 related records sideloaded, into `included` array.
 
-#### Example
+#### Handler Exmaple Code
 
 ```go
 func CreateBlog(w http.ResponseWriter, r *http.Request) {
@@ -151,7 +189,7 @@ func CreateBlog(w http.ResponseWriter, r *http.Request) {
 }
 ```
 
-### List
+### List Records Example
 
 #### `MarshalManyPayload`
 
@@ -188,7 +226,7 @@ the first time.  For example when you fetch the `Blog`s from the db
 FetchBlogs() ([]interface{}, error)
 ```
 
-#### Example
+#### Handler Example Code
 
 ```go
 func ListBlogs(w http.ResponseWriter, r *http.Request) {

doc.go

@@ -0,0 +1,63 @@
+/*
+
+You can keep your model structs as is and use struct field tags to indicate to jsonapi
+how you want your response built or your request deserialzied. What about my relationships?
+jsonapi supports relationships out of the box and will even side load them in your response
+into an "included" array--that contains associated objects.
+
+jsonapi uses StructField tags to annotate the structs fields that you already have and use
+in your app and then reads and writes jsonapi.org output based on the instructions you give
+the library in your jsonapi tags.
+
+Example structs using a Blog > Post > Comment structure,
+
+				type Blog struct {
+						Id            int       `jsonapi:"primary,blogs"`
+						Title         string    `jsonapi:"attr,title"`
+						Posts         []*Post   `jsonapi:"relation,posts"`
+						CurrentPost   *Post     `jsonapi:"relation,current_post"`
+						CurrentPostId int       `jsonapi:"attr,current_post_id"`
+						CreatedAt     time.Time `jsonapi:"attr,created_at"`
+						ViewCount     int       `jsonapi:"attr,view_count"`
+				}
+
+				type Post struct {
+						Id       int        `jsonapi:"primary,posts"`
+						BlogId   int        `jsonapi:"attr,blog_id"`
+						Title    string     `jsonapi:"attr,title"`
+						Body     string     `jsonapi:"attr,body"`
+						Comments []*Comment `jsonapi:"relation,comments"`
+				}
+
+				type Comment struct {
+						Id     int    `jsonapi:"primary,comments"`
+						PostId int    `jsonapi:"attr,post_id"`
+						Body   string `jsonapi:"attr,body"`
+				}
+
+jsonapi Tag Reference
+
+Value, primary: "primary,<type field output>"
+
+This indicates that this is the primary key field for this struct type. Tag
+value arguments are comma separated.  The first argument must be, "primary", and
+the second must be the name that should appear in the "type" field for all data
+objects that represent this type of model.
+
+Value, attr: "attr,<key name in attributes hash>"
+
+These fields' values should end up in the "attribute" hash for a record.  The first
+argument must be, "attr', and the second should be the name for the key to display in
+the the "attributes" hash for that record.
+
+Value, relation: "relation,<key name in relationships hash>"
+
+Relations are struct fields that represent a one-to-one or one-to-many to other structs.
+jsonapi will traverse the graph of relationships and marshal or unmarshal records.  The first
+argument must be, "relation", and the second should be the name of the relationship, used as
+the key in the "relationships" hash for the record.
+
+Use the methods below to Marshal and Unmarshal jsonapi.org json payloads.
+
+*/
+package jsonapi