README.md in banditmask-0.2.1 vs README.md in banditmask-0.3.0

@@ -20,11 +20,13 @@
 
     $ gem install banditmask
 
 ## Usage
 
-Create a class which inherits from `BanditMask`, and declare the available bit
+### BanditMask
+
+Create a class which inherits from BanditMask, and declare the available bit
 names and their corresponding values.
 
 ```ruby
 class ChmodMask < BanditMask
   bit :read,    0b001
@@ -45,29 +47,33 @@
 ```
 
 Enable bits by name.
 
 ```ruby
-mask << :read << :write
+mask << :read << :execute
 ```
 
 Ask whether specific bits are enabled.
 
 ```ruby
-mask.include? :read    # => true
-mask.include? :write   # => true
-mask.include? :execute # => false
+mask.include? :read           # => true
+mask.include? :write          # => false
+mask.include? :execute        # => true
+mask.include? :read, :write   # => false
+mask.include? :read, :execute # => true
 ```
 
 Retrieve a list of all currently enabled bits.
 
 ```ruby
-mask.bits # => [:read, :write]
+mask.bits # => [:read, :execute]
 ```
 
-In an class with a bitmask attribute, extend `BanditMask::Banditry` and call
-`BanditMask::Banditry.bandit_mask` to add accessor methods for working with the
+### BanditMask::Banditry
+
+In a class with a bitmask attribute, extend BanditMask::Banditry and call
+BanditMask::Banditry.bandit_mask to add accessor methods for working with the
 bitmask attribute.
 
 ```ruby
 class ObjectWithBitmaskAttribute
   attr_accessor :bitmask
@@ -75,31 +81,38 @@
   extend BanditMask::Banditry
   bandit_mask :bitmask, as: :bits, with: ChmodMask
 end
 
 obj = ObjectWithBitmaskAttribute.new
-obj.bitmask = 0b011
+obj.bitmask = 0b001
 ```
 
-This gives you a reader method which delegates to `BanditMask#bits`.
+This gives you a reader method which returns the BanditMask representation
+of the bitmask attribute.
 
 ```ruby
-obj.bits # => [:read, :write]
+obj.bits # => #<ChmodMask:0x007f941b9518c8 @bitmask=1>
 ```
 
-It also gives you a writer method which lets you overwrite the bitmask.
+It also gives you a writer method which lets you modify the bitmask. The
+writer accepts BanditMask objects or an Array of bits.
 
 ```ruby
+obj.bits |= :write
+obj.bitmask # => 3
 obj.bits = [:read, :execute]
 obj.bitmask # => 5
 ```
 
-Finally, it gives you a query method for checking whether a particular bit is
+Finally, it gives you a query method for checking whether particular bits are
 set on the bitmask.
 
 ```ruby
-obj.has? :read  # => true
-obj.has? :write # => false
+obj.bits? :read           # => true
+obj.bits? :write          # => false
+obj.bits? :execute        # => true
+obj.bits? :read, :write   # => false
+obj.bits? :read, :execute # => true
 ```
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run