Merge pull request #1503 from feministy/0-8-stable-poro-documentation

[0.8-stable] additional documentation for POROs

CHANGELOG.md

@@ -1,5 +1,7 @@
 # UNRELEASED
 
+* Add documentation with example to `README` for POROs and alternative ORMs
+
 # VERSION 0.8.1
 
 * Fix bug whereby a serializer using 'options' would blow up.

README.md

@@ -45,18 +45,35 @@ the serializer generator:
 $ rails g serializer post
 ```
 
-### Support for PORO's and other ORM's.
+### Support for POROs and other ORMs.
 
 Currently `ActiveModel::Serializers` adds serialization support to all models
-that descend from `ActiveRecord` or include `Mongoid::Document`. If you are
-using another ORM, or if you are using objects that are `ActiveModel`
-compliant but do not descend from `ActiveRecord` or include
-`Mongoid::Document`, you must add an include statement for
-`ActiveModel::SerializerSupport` to make models serializable. If you
-also want to make collections serializable, you should include
+that descend from `ActiveRecord` or include `Mongoid::Document`. If you are:
+
+- using another ORM, or
+- using objects that are `ActiveModel` compliant but do not descend from
+`ActiveRecord` *or* include `Mongoid::Document`
+
+You must add an include statement for `ActiveModel::SerializerSupport` to
+make models serializable. 
+
+If you also want to make collections serializable, you should include
 `ActiveModel::ArraySerializerSupport` into your ORM's
 relation/criteria class.
 
+Example model (`app/models/avatar.rb`):
+
+```ruby
+class Avatar
+  include ActiveModel::SerializerSupport
+  # etc, etc
+end
+```
+
+If your classes follow the naming conventions prescribed by `ActiveModel`,
+you don't need to do anything different in your controller to render the
+serialized json.
+
 # ActiveModel::Serializer
 
 All new serializers descend from ActiveModel::Serializer