Merge pull request #631 from theirishpenguin/penguin/320-more-user-friendly-docs-for-context

More user friendly docs for context

Author: lgebhardt

README.md

@@ -21,6 +21,7 @@ backed by ActiveRecord models or by custom objects.
 * [Usage] (#usage)
   * [Resources] (#resources)
     * [JSONAPI::Resource] (#jsonapiresource)
+    * [Context] (#context)
     * [Attributes] (#attributes)
     * [Primary Key] (#primary-key)
     * [Model Name] (#model-name)
@@ -160,6 +161,28 @@ In the above example vehicles are immutable. A call to `/vehicles` or `/vehicles
 of either `car` or `boat`. But calls to PUT or POST a `car` must be made to `/cars`. The rails models backing the above
 code use Single Table Inheritance.
 
+#### Context
+
+Sometimes you will want to access things such as the current logged in user (and other state only available within your controllers) from within your resource classes. To make this state available to a resource class you need to put it into the context hash - this can be done via a `context` method on one of your controllers or across all controllers using ApplicationController.
+
+For example:
+
+```ruby
+class ApplicationController < JSONAPI::ResourceController
+  def context
+    {current_user: current_user}
+  end
+end
+
+# Specific resource controllers derive from ApplicationController
+# and share its context
+class PeopleController < ApplicationController
+
+end
+```
+
+You can put things that affect serialization and resource configuration into the context.
+
 #### Attributes
 
 Any of a resource's attributes that are accessible must be explicitly declared. Single attributes can be declared using
@@ -1140,26 +1163,6 @@ A jsonapi-controller generator is avaliable
 rails generate jsonapi:controller contact
 ```
 
-###### Context
-
-The context that's used for serialization and resource configuration is set by the controller's `context` method.
-
-For example:
-
-```ruby
-class ApplicationController < JSONAPI::ResourceController
-  def context
-    {current_user: current_user}
-  end
-end
-
-# Specific resource controllers derive from ApplicationController
-# and share its context
-class PeopleController < ApplicationController
-
-end
-```
-
 ###### Serialization Options
 
 Additional options can be passed to the serializer using the `serialization_options` method.