README.markdown in ohm-0.0.16 vs README.markdown in ohm-0.0.17

@@ -5,11 +5,11 @@
 
 
 Description
 -----------
 
-Ohm is a library that allows to store an object in
+Ohm is a library for storing objects in
 [Redis](http://code.google.com/p/redis/), a persistent key-value
 database. It includes an extensible list of validations and has very
 good performance.
 
 
@@ -26,10 +26,12 @@
 
 If you don't have Ohm, try this:
 
     $ sudo gem install ohm
 
+Or you can grab the code from [http://github.com/soveran/ohm](http://github.com/soveran/ohm).
+
 Now, in an irb session you can test the Redis adapter directly:
 
     >> require "ohm"
     => true
     >> Ohm.connect
@@ -60,14 +62,29 @@
       def validate
         assert_present :name
       end
     end
 
+All models have the `id` attribute built in, you don't need to declare it.
+
+This is how you interact with ids:
+
+    event = Event.create :name => "Ohm Worldwide Conference 2031"
+    event.id
+    # => 1
+
+    # Find an event by id
+    event == Event[1]
+    # => true
+
+    # Trying to find a non existent event
+    Event[2]
+    # => nil
+
 This example shows some basic features, like attribute declarations and
 validations. Keep reading to find out what you can do with models.
 
-
 Attribute types
 ---------------
 
 Ohm::Model provides four attribute types: `attribute`, `set`, `list` and
 `counter`.
@@ -97,11 +114,29 @@
 of the value is not allowed. You can retrieve, increase or decrease
 the value, but you can not assign it. In the example above, we used a
 counter attribute for tracking votes. As the incr and decr operations
 are atomic, you can rest assured a vote won't be counted twice.
 
+Associations
+------------
 
+Ohm lets you use collections (lists and sets) to represent associations.
+For this, you only need to provide a second paramenter when declaring a
+list or a set:
+
+    set :attendees, Person
+
+After this, everytime you refer to `event.attendees` you will be talking
+about instances of the model `Person`. If you want to get the raw values
+of the set, you can use `event.attendees.raw`.
+
+The `attendees` collection also exposes two sorting methods: `sort`
+returns the elements ordered by `id`, and `sort_by` receives a parameter
+with an attribute name, which will determine the sorting order. Both
+methods receive an options hash which is explained in the documentation
+for {Ohm::Attributes::Collection#sort}.
+
 Indexes
 -------
 
 An index is a set that's handled automatically by Ohm. For any index declared,
 Ohm maintains different sets of objects ids for quick lookups.
@@ -204,11 +239,12 @@
       assert_unique :qux
     end
 
 If all the assertions fail, the following errors will be present:
 
-    obj.errors #=> [[:foo, :not_present], [:bar, :not_numeric], [:baz, :format], [[:qux], :not_unique]]
+    obj.errors
+    # => [[:foo, :not_present], [:bar, :not_numeric], [:baz, :format], [[:qux], :not_unique]]
 
 Note that the error for assert_unique wraps the field in an array.
 The purpose for this is to standardize the format for both single and
 multicolumn indexes.
 
@@ -227,11 +263,12 @@
     error_messages = @model.errors.present do |e|
       e.on [:name, :not_present], "Name must be present"
       e.on [:account, :not_present], "You must supply an account"
     end
 
-    error_messages #=> ["Name must be present", "You must supply an account"]
+    error_messages
+    # => ["Name must be present", "You must supply an account"]
 
 Having the error message definitions in the views means you can use any
 sort of helpers. You can also use blocks instead of strings for the
 values. The result of the block is used as the error message:
 
@@ -239,6 +276,7 @@
       e.on [:email, :not_unique] do
         "The email #{@model.email} is already registered."
       end
     end
 
-    error_messages #=> ["The email [e-mail] is already registered."]
+    error_messages
+    # => ["The email [e-mail] is already registered."]