1 files changed, 97 insertions, 30 deletions
diff --git a/railties/doc/guides/source/creating_plugins/migration_generator.txt b/railties/doc/guides/source/creating_plugins/migration_generator.txt
index 598a0c8437..f4fc32481c 100644
--- a/railties/doc/guides/source/creating_plugins/migration_generator.txt
+++ b/railties/doc/guides/source/creating_plugins/migration_generator.txt
@@ -1,42 +1,79 @@
-== Create a migration generator ==
+== Create a generator ==
 
-When you created the plugin above, you specified the --with-generator option, so you already have the generator stubs in your plugin.
+Many plugins ship with generators.  When you created the plugin above, you specified the --with-generator option, so you already have the generator stubs in 'vendor/plugins/yaffle/generators/yaffle'.
 
-We'll be relying on the built-in rails generate template for this tutorial.  Going into the details of generators is beyond the scope of this tutorial.
+Building generators is a complex topic unto itself and this section will cover one small aspect of generators:  creating a generator that adds a time-stamped migration.
 
-Type:
+To create a generator you must:
 
-    script/generate
+ * Add your instructions to the 'manifest' method of the generator
+ * Add any necessary template files to the templates directory
+ * Test the generator manually by running various combinations of `script/generate` and `script/destroy`
+ * Update the USAGE file to add helpful documentation for your generator
 
-You should see the line:
+=== Testing generators ===
 
-    Plugins (vendor/plugins): yaffle
+Many rails plugin authors do not test their generators, however testing generators is quite simple.  A typical generator test does the following:
 
-When you run `script/generate yaffle` you should see the contents of your USAGE file.  For this plugin, the USAGE file looks like this:
+ * Creates a new fake rails root directory that will serve as destination
+ * Runs the generator forward and backward, making whatever assertions are necessary
+ * Removes the fake rails root
 
+For the generator in this section, the test could look something like this:
+
+*vendor/plugins/yaffle/test/yaffle_generator_test.rb*
+
+[source, ruby]
 ------------------------------------------------------------------
-Description:
-    Creates a migration that adds yaffle squawk fields to the given model
+require File.dirname(__FILE__) + '/test_helper.rb'
+require 'rails_generator'
+require 'rails_generator/scripts/generate'
+require 'rails_generator/scripts/destroy'
 
-Example:
-    ./script/generate yaffle hickwall
+class GeneratorTest < Test::Unit::TestCase
 
-    This will create:
-        db/migrate/TIMESTAMP_add_yaffle_fields_to_hickwall
+  def fake_rails_root
+    File.join(File.dirname(__FILE__), 'rails_root')
+  end
+  
+  def file_list
+    Dir.glob(File.join(fake_rails_root, "db", "migrate", "*"))
+  end
+
+  def setup
+    FileUtils.mkdir_p(fake_rails_root)
+    @original_files = file_list
+  end
+
+  def teardown
+    FileUtils.rm_r(fake_rails_root)
+  end
+  
+  def test_generates_correct_file_name
+    Rails::Generator::Scripts::Generate.new.run(["yaffle", "bird"], :destination => fake_rails_root)
+    new_file = (file_list - @original_files).first
+    assert_match /add_yaffle_fields_to_bird/, new_file
+  end
+  
+end
 ------------------------------------------------------------------
 
-Now you can add code to your generator:
+You can run 'rake' from the plugin directory to see this fail.  Unless you are doing more advanced generator commands it typically suffices to just test the Generate script, and trust that rails will handle the Destroy and Update commands for you.
+
+=== Adding to the manifest ===
+
+This example will demonstrate how to use one of the built-in generator methods named 'migration_template' to create a migration file.  To start, update your generator file to look like this:
+
+*vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb*
 
 [source, ruby]
 ------------------------------------------------------------------
-# File: vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
-
 class YaffleGenerator < Rails::Generator::NamedBase
   def manifest
     record do |m|
       m.migration_template 'migration:migration.rb', "db/migrate", {:assigns => yaffle_local_assigns,
         :migration_file_name => "add_yaffle_fields_to_#{custom_file_name}"
-       }
+      }
     end
   end
 
@@ -52,38 +89,68 @@ class YaffleGenerator < Rails::Generator::NamedBase
         assigns[:class_name] = "add_yaffle_fields_to_#{custom_file_name}"
         assigns[:table_name] = custom_file_name
         assigns[:attributes] = [Rails::Generator::GeneratedAttribute.new("last_squawk", "string")]
-        assigns[:attributes] << Rails::Generator::GeneratedAttribute.new("last_squawked_at", "datetime")
       end
     end
 end
 ------------------------------------------------------------------
 
-Note that you need to be aware of whether or not table names are pluralized.
+The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement.  It reuses the built in rails `migration_template` method, and reuses the built-in rails migration template.
 
-This does a few things:
+It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names.  This way people using your generator won't have to manually change the generated files if they've turned pluralization off.
 
- * Reuses the built in rails `migration_template` method.
- * Reuses the built-in rails migration template.
+=== Manually test the generator ===
 
-When you run the generator like
+To run the generator, type the following at the command line:
+
+------------------------------------------------------------------
+./script/generate yaffle bird
+------------------------------------------------------------------
 
-    script/generate yaffle bird
+and you will see a new file:
 
-You will see a new file:
+*db/migrate/20080529225649_add_yaffle_fields_to_birds.rb*
 
 [source, ruby]
 ------------------------------------------------------------------
-# File: db/migrate/20080529225649_add_yaffle_fields_to_birds.rb
-
 class AddYaffleFieldsToBirds < ActiveRecord::Migration
   def self.up
     add_column :birds, :last_squawk, :string
-    add_column :birds, :last_squawked_at, :datetime
   end
 
   def self.down
-    remove_column :birds, :last_squawked_at
     remove_column :birds, :last_squawk
   end
 end
 ------------------------------------------------------------------
+
+
+=== The USAGE file ===
+
+Rails ships with several built-in generators.  You can see all of the generators available to you by typing the following at the command line:
+
+------------------------------------------------------------------
+script/generate
+------------------------------------------------------------------
+
+You should see something like this:
+
+------------------------------------------------------------------
+Installed Generators
+  Plugins (vendor/plugins): yaffle
+  Builtin: controller, integration_test, mailer, migration, model, observer, plugin, resource, scaffold, session_migration
+------------------------------------------------------------------
+
+When you run `script/generate yaffle` you should see the contents of your 'vendor/plugins/yaffle/generators/yaffle/USAGE' file.  
+
+For this plugin, update the USAGE file looks like this:
+
+------------------------------------------------------------------
+Description:
+    Creates a migration that adds yaffle squawk fields to the given model
+
+Example:
+    ./script/generate yaffle hickwall
+
+    This will create:
+        db/migrate/TIMESTAMP_add_yaffle_fields_to_hickwall
+------------------------------------------------------------------