README.rdoc in doeskeyvalue-0.1.0 vs README.rdoc in doeskeyvalue-0.1.1

@@ -10,71 +10,77 @@
 
   gem install doeskeyvalue
 
 And add a gem dependency to your Gemfile:
 
-  gem "doeskeyvalue", ">=0.0.1"
+  gem "doeskeyvalue", ">=0.1.0"
 
 
-== Example (TODO: Update this with new API)
+== Example 
 
-To add document_fields to your ActiveRecord object, first add a text column to your class' backing table that will hold your document content. By default, do_document_fields will expect this column to be named "document", but you can override that easily.
+Quick and simple. First, add the declaration to your ActiveRecord model:
 
-Once you've migrated that change into your model, here's a sample of hold to add document-style blob fields to your object:
+  doeskeyvalue :settings
+  
+In this invocation, "settings" is the name of TEXT or BLOB field on your model's database table. Think
+of it as something you'd typically serialize, but would prefer solid accessor and finding behavior on.
 
-  class ObjectWithBlob < ActiveRecord::Base
+To add keys to your document, using the name of the field you provided, before (in this case 
+"settings"), add keys individually like so:
 
-    # Declare that we are using document blobs in a particular column of this object:
-    do_document_fields
+  settings_key :uid
+  settings_key :email
+  settings_key :name
+  
+This adds a uid, email, and name field to your record. You can use these fields just like regular 
+columns on your ActiveRecord object, but they're happily stored within your TEXT/BLOB column at the
+database level. Check it out:
 
-    # Declare the columns we are adding to our document:
-    document_field :name, String
-    document_field :phone, String
-    document_field :age, Integer
+  mod = Model.new
+  
+  mod.uid = "mccolin"
+  => "mccolin"
+  
+  mod.uid
+  => "mccolin"
+  
+You can see the serialized key-value structure at any time, as well. Just access your old filed:
 
-    # Declare the document fields you'd like to track with indexes:
-    document_index :name
+  mod.settings
+  => {:uid=>"mccolin"}
+  
+At this point, we have a fancy serialized Hash on our hands. What we really want to be able to do is
+search for objects of type Model that have certain values. That's possible, too. First, generate the
+necessary migration:
 
+  rails g doeskeyvalue
+  
+This creates db/migrate/XXX_create_key_value_index.rb for you. Migrate your database:
 
-    # If we wanted to change the name of the column in which we store the document, we'd do this:
-    # do_document_fields :something_other_than_document. Like so:
-    
-    do_document_fields :settings
-    
-    # Changing the name of the column gives you a specifically-formatted field-definition method:
-    
-    settings_field :age
-    settings_field :sex
-    settings_field :location
-    
-    # This also provides a customized way to index:
-    
-    settings_index :location
+  rake db:migrate
+  
+Now, you can declare keys that you'd like to be searchable within Model like so:
 
-  end
+  settings_index :uid
+  settings_index :email
+  
+Now, you've added powerful finders to your objects. As your objects are created, accessed, and updated,
+metadata in your index table will be updated that allows you to search against those objects similarly
+to how you'd perform lookups with a regular finder. Like so:
 
+  Model.find_all_by_uid(123)
+  => [#<Model:0x000001016b51a0 @settings=>{:uid=>123}>, #<Model:0x000001016b51a0 @settings=>{:uid=>123}>, ...]
+  
+  Model.find_all_with_settings(:email=>"[e-mail]")
+  => [#<Model:0x000001016b51a0 @settings=>{:email=>"foo@bar"}>, ...]
 
-Now, you can add and remove new fields to this object within the document as simply as adding or removing declarations of "document_field".
+You can only run finds on keys for which you've added an index, but you can add and remove indexes as
+necessary simply by removing the index declaration from your model.
 
-
-Once you've added any indices to your model's fields, you'll want to be sure to build your supporting index tables. We use separate tables with database-level indexing to support indexed lookups of data in your document_field attributes. Build these tables by running this rake task:
-
-  rake db:migrate:document_indexes
-
-
-Now, you can use strictly-provided finders to find your objects by their document field attributes. Considering the model we described above, you can lookup by any *indexed* field like so:
-
-  obj = ObjectWithBlob.find_by_name("Charlie")
-  => [#<ObjectWithBlob id: 412, document: {:name=>"Charlie", :phone=>"212-555-1234", :age=>34}, created_at: "2010-03-22 20:49:03", updated_at: "2010-03-22 20:49:03">]
-
-Finders are only added to document fields that are indexed. Finders also are all "find_all" lookups on equality.
-
-If you'd like to use special sub-searching within any of your document-formatted fields, you can use the hash-based search conditions. Given the "settings" document declared in the example above, we can now also do this:
-
-  obj = ObjectWithBlob.find_with_settings(:location=>"San Francisco, CA")
-  => [#<ObjectWithBlob id: 412, settings: {:age=>32, :sex=>"Female", :location=>"San Francisco, CA"}, created_at: "2010-03-22 20:49:03", updated_at: "2010-03-22 20:49:03">]
-
-It's simple.
+Likewise, you can remove keys from any model by removing the key declaration. This allows you to add
+and remove keys from every ActiveRecord object at will, without having to build any migrations, but you
+can still reap the benefits of whatever SQL-backed relational database you've chosen for the bulk of
+your application's heavy lifting.
 
 
 == Prior Versions
 
 DoesKeyValue is a much newer and cleaner version of the old "do_document_fields" plugin for prior versions