Updates to the documentation

ARCH.md

@@ -6,32 +6,18 @@ modular and easy to tailor to your specific needs.
 ### `Config`
 
 Holds configuration information for Undestroy.  An instance is created
-globally and serves as defaults for each model using Undestroy.  Each
-model also creates its own instance of Config allowing any model to
-override any of the globally configurable options.
+globally and serves as defaults for each model using Undestroy, but each
+model has its own unique configuration allowing developer flexibility.
 
-To change global defaults use this configuration DSL:
+Each of the core classes `Archive`, `Restore`, and `Transfer` can be
+configured in the `:internals` hash option on a per model basis allowing
+the developer to provide custom classes for the various actions
+Undestroy provides.
 
-```ruby
-Undestroy::Config.configure do |config|
-  config.abstract_class = ArchiveModel
-  config.fields = {
-    :deleted_at => proc { Time.now },
-    :deleted_by_id => proc { User.current.id if User.current }
-  }
-end
-```
-
-This changes the default abstract class from ActiveRecord::Base to a
-model called ArchiveModel.  This also sets the default fields to include
-a deleted_by_id which automatically sets the current user as the deleter
-of the record.
-
-Possible configuration options are listed in the _Usage_ section above.
 
 ### `Archive`
 
-Map the source model's schema to the archive model's and initiate the
+Map the source model's schema to the target model's and initiate the
 transfer through `Transfer`.  When `run` is called the Transfer is
 initialized with a primitive hash mapping the schema to the archive
 table.
@@ -44,7 +30,9 @@ Initialized with:
 ### `Restore`
 
 Map the archive model's schema to the source model's and initiate the
-transfer through `Transfer`
+transfer through `Transfer` When `run` is called the `Transfer` is
+initialized with a primitive hash mapping the schema from the archive
+table to the source table.
 
 Initialized with:
 
@@ -71,14 +59,15 @@ is bound to the `before_destroy` callback that performs the archiving
 functions.  Any of the code that handles ActiveRecord specific logic
 lives in here.
 
-Initialized with: *Config options from above*
+Initialized with: *Options for `Config` class*
 
 Attributes:
 
+* `model`: The AR model ths instance binds
 * `config`: Returns this model's config object
-* `model`: The AR model this instnace was created for
 
 Methods:
 
 * `before_destroy`: Perform the archive process
+* `self.add(klass)`: Performs patch to provided klass needed for binding
 

README.md

@@ -1,11 +1,12 @@
 # Undestroy
 
-Allow copying records to alternate table before destroying an
-ActiveRecord model for archiving purposes.  Data will be mapped
-one-to-one to the archive table schema.  Additional fields can also be
-configured for additional tracking information.  -Archive table schema
-will automatically be updated when the parent model's table is migrated
-through Rails.- (not yet)
+Provides automatic archiving of ActiveRecord models before the object is
+destroyed.  It is designed to be database agnostic and easy to extend
+with custom functionality.  Migrations will be run in parallel on the
+archive table when run on the original table.  Additional archive schema
+can be appended to the archive table for storing tracking data (default:
+deleted_at).
+
 
 ## Installation
 
@@ -45,19 +46,28 @@ This method can also accept an options hash or block to further
 customize Undestroy to your needs.  Here are some of the common options:
 
 * `:table_name`:  use this table for archiving (Defaults to the
-  source class's table_name prefixed with "archive_").
+  source class's table_name prefixed with the :prefix option).
+* `:prefix`: use this prefix for table names -- if :table_name is set
+  this option does nothing (default: "archive_")
 * `:abstract_class`:  use this as the base class for the target_class
-  specify an alternate for custom extensions / DB connections (defaults
-  to ActiveRecord::Base)
-* `:migrate`:  Should Undestroy migrate the archive table together with
-  this model's table (default: true)
+  specify an alternate for custom extensions (defaults to
+  ActiveRecord::Base)
+* `:migrate`:  Determines whether Undestroy will handle automatic
+  migrations (default: true)
+* `:indexes`: When :migrate is true should indexes be migrated as well?
+  (default: false) 
+* `add_field(name, type, value=nil, &block)`:  method on the Config
+  object that configures a new field for the archive table.  The return
+  value of the block or value of `value` is used as the value of the 
+  field.  The block will be passed the instance of the object to be
+  archived as an argument.
 
 You can also use a block to handle the configuration:
 
 ```ruby
-class Person < ActiveRecord::Base
+class Post < ActiveRecord::Base
   undestroy do |config|
-    config.table_name "old_people"
+    config.prefix = "old_"
     config.add_field :deleted_by_id, :integer do |instance|
       User.current.id if User.current
     end
@@ -71,6 +81,9 @@ Advanced Options:
   fields you would like to include on the archive table.  The preferred
   method of specificying fields is through the add_field method with the
   block configuration method.  (defaults to deleted_at timestamp).
+* `:model_paths`: Array of paths where Undestroy models live.  This is
+  used to autoload models before migrations are run (default:
+  `Rails.root.join('app', 'models')`).
 * `:source_class`:  the AR model of the originating data.  Set
   automatically to class `undestroy` method is called on.
 * `:target_class`:  use this AR model for archiving.  Set automatically
@@ -79,11 +92,19 @@ Advanced Options:
   keys are `:archive`, `:transfer` and `:restore`.  Defaults to
   corresponding internal classes.  Customize to your heart's content.
 
-```
-$ person = Person.find(1)
-$ person.destroy
-# => Inserts person data into archive_people table
-# => Deletes person data from people table
+```ruby
+person = Person.create(:name => "Billy Mcgeeferson")
+# Creates a new person record in people table
+person.destroy
+# => Inserts record in archive_people table
+# => Deletes record from people table
+People.restore(person.id)
+People.archived.where(:name => "Billy Mcgeeferson").restore_all
+# => Two ways to restore the record back to the people table
+People.archived.find(person.id).restore_copy
+# => Restores the record, but doesn't remove the archived record
+People.find(person.id).destroy!
+# => Destroys the record without archiving
 ```
 
 ## Configuring
@@ -104,6 +125,18 @@ Options set in this block will be the default for all models with
 undestroy activated.  They can be overriden with options passed to the
 `undestroy` method
 
+## Architecture
+
+Checkout the ARCH.md file for docs on how the gem is setup internally,
+or just read the code.  My goal was to make it easy to understand and
+extend.
+
+Enjoy!
+
+## Acknowledgements
+
+* acts_as_archive author Winton Welsh for inspiration
+
 ## Contributing
 
 1. Fork it