README.md in virtus-0.4.2 vs README.md in virtus-0.5.0

@@ -39,23 +39,63 @@
   attribute :age, Integer
   attribute :birthday, DateTime
 end
 
 user = User.new(:name => 'Piotr', :age => 28)
-user.attributes # => { :name => "Piotr", :age => 28 }
+user.attribute_set # => { :name => "Piotr", :age => 28 }
 
 user.name # => "Piotr"
 
 user.age = '28' # => 28
 user.age.class # => Fixnum
 
 user.birthday = 'November 18th, 1983' # => #<DateTime: 1983-11-18T00:00:00+00:00 (4891313/2,0/1,2299161)>
 ```
 
+### Using Virtus With Modules
 
-**Default values**
+You can create modules extended with virtus and define attributes for later
+inclusion in your classes:
 
+```ruby
+module Name
+  include Virtus
+
+  attribute :name, String
+end
+
+module Age
+  include Virtus
+
+  attribute :age, Integer
+end
+
+class User
+  include Name, Age
+end
+
+user = User.new(:name => 'John', :age => '30')
+```
+
+### Dynamically Extending Instances
+
+It's also possible to dynamically extend an object with Virtus:
+
+```ruby
+class User
+  # nothing here
+end
+
+user = User.new
+user.extend(Virtus)
+user.attribute :name, String
+user.name = 'John'
+user.name # => 'John'
+```
+
+### Default Values
+
 ``` ruby
 class Page
   include Virtus
 
   attribute :title, String
@@ -82,11 +122,11 @@
 page.views        # => 0
 page.published    # => false
 page.editor_title # => "UNPUBLISHED: Virtus README"
 ```
 
-**Embedded Value**
+### Embedded Value
 
 ``` ruby
 class City
   include Virtus
 
@@ -113,11 +153,11 @@
 
 user.address.street # => "Street 1/2"
 user.address.city.name # => "NYC"
 ```
 
-**Collection Member Coercions**
+### Collection Member Coercions
 
 ``` ruby
 # Support "primitive" classes
 class Book
   include Virtus
@@ -161,11 +201,11 @@
 user.phone_numbers # => [#<PhoneNumber:0x007fdb2d3bef88 @number="212-555-1212">, #<PhoneNumber:0x007fdb2d3beb00 @number="919-444-3265">]
 
 user.addresses # => #<Set: {#<Address:0x007fdb2d3be448 @address="1234 Any St.", @locality="Anytown", @region="DC", @postal_code="21234">}>
 ```
 
-**Value Objects**
+### Value Objects
 
 ``` ruby
 class GeoLocation
   include Virtus::ValueObject
 
@@ -194,11 +234,11 @@
   :location => { :latitude => 37.160317, :longitude => -98.437500 })
 
 venue.location === venue_other.location # => true
 ```
 
-**Adding Coercions**
+### Adding Coercions
 
 Virtus comes with a builtin coercion library.
 It's super easy to add your own coercion classes.
 Take a look:
 
@@ -233,11 +273,11 @@
 user = User.new(:name => 'Piotr', :password => 'foobar')
 user.name # => 'Piotr'
 user.password # => '3858f62230ac3c915f300c664312c63f'
 ```
 
-**Custom Attributes**
+### Custom Attributes
 
 ``` ruby
 require 'json'
 
 module MyApp
@@ -262,10 +302,9 @@
 
 user = MyApp::User.new
 user.info = '{"email":"[e-mail]"}' # => {"email"=>"[e-mail]"}
 user.info.class # => Hash
 ```
-
 
 Credits
 -------
 
 * Dan Kubb ([dkubb](https://github.com/dkubb))