Wordsmith generator USAGEs.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6884 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

11 files changed, 104 insertions, 163 deletions

diff --git a/railties/lib/rails_generator/generators/components/controller/USAGE b/railties/lib/rails_generator/generators/components/controller/USAGE
index 246a3d652b..d4fae60c81 100644
--- a/railties/lib/rails_generator/generators/components/controller/USAGE
+++ b/railties/lib/rails_generator/generators/components/controller/USAGE
@@ -1,17 +1,16 @@
 Description:
-    The controller generator creates stubs for a new controller and its views.
+    Stubs out a new controller and its views. Pass the controller name, either
+    CamelCased or under_scored, and a list of views as arguments.
 
-    The generator takes a controller name and a list of views as arguments.
-    The controller name may be given in CamelCase or under_score and should
-    not be suffixed with 'Controller'.  To create a controller within a
-    module, specify the controller name as 'module/controller'.
+    To create a controller within a module, specify the controller name as a
+    path like 'parent_module/controller_name'.
 
-    The generator creates a controller class in app/controllers with view
-    templates in app/views/controller_name, a helper class in app/helpers,
-    and a functional test suite in test/functional.
+    This generates a controller class in app/controllers, view templates in
+    app/views/controller_name, a helper class in app/helpers, and a functional
+    test suite in test/functional.
 
 Example:
-    ./script/generate controller CreditCard open debit credit close
+    `./script/generate controller CreditCard open debit credit close`
 
     Credit card controller with URLs like /credit_card/debit.
         Controller: app/controllers/credit_card_controller.rb
@@ -20,7 +19,7 @@ Example:
         Test:       test/functional/credit_card_controller_test.rb
 
 Modules Example:
-    ./script/generate controller 'admin/credit_card' suspend late_fee
+    `./script/generate controller 'admin/credit_card' suspend late_fee`
 
     Credit card admin controller with URLs /admin/credit_card/suspend.
         Controller: app/controllers/admin/credit_card_controller.rb
diff --git a/railties/lib/rails_generator/generators/components/integration_test/USAGE b/railties/lib/rails_generator/generators/components/integration_test/USAGE
index d1ed71a408..09e2691f69 100644
--- a/railties/lib/rails_generator/generators/components/integration_test/USAGE
+++ b/railties/lib/rails_generator/generators/components/integration_test/USAGE
@@ -1,14 +1,8 @@
 Description:
-    The model generator creates a stub for a new integration test.
-
-    The generator takes an integration test name as its argument.  The test
-    name may be given in CamelCase or under_score and should not be suffixed
-    with 'Test'.
-
-    The generator creates an integration test class in test/integration.
+    Stubs out a new integration test. Pass the name of the test, either
+    CamelCased or under_scored, as an argument. The new test class is
+    generated in test/integration/testname_test.rb
 
 Example:
-    ./script/generate integration_test GeneralStories
-
-    This will create a GeneralStores integration test:
-        test/integration/general_stories_test.rb
+    `./script/generate integration_test GeneralStories` creates a GeneralStories
+    integration test in test/integration/general_stories_test.rb
diff --git a/railties/lib/rails_generator/generators/components/mailer/USAGE b/railties/lib/rails_generator/generators/components/mailer/USAGE
index 8224a25190..61a649ed4d 100644
--- a/railties/lib/rails_generator/generators/components/mailer/USAGE
+++ b/railties/lib/rails_generator/generators/components/mailer/USAGE
@@ -1,18 +1,16 @@
 Description:
-    The mailer generator creates stubs for a new mailer and its views.
+    Stubs out a new mailer and its views. Pass the mailer name, either
+    CamelCased or under_scored, and an optional list of emails as arguments.
 
-    The generator takes a mailer name and a list of views as arguments.
-    The mailer name may be given in CamelCase or under_score.
-
-    The generator creates a mailer class in app/models with view templates
-    in app/views/mailer_name, and a test suite with fixtures in test/unit.
+    This generates a mailer class in app/models, view templates in
+    app/views/mailer_name, a unit test in test/unit, and fixtures in
+    test/fixtures.
 
 Example:
-    ./script/generate mailer Notifications signup forgot_password invoice
+    `./script/generate mailer Notifications signup forgot_password invoice`
 
-    This will create a Notifications mailer class:
+    creates a Notifications mailer class, views, test, and fixtures:
         Mailer:     app/models/notifications.rb
         Views:      app/views/notifications/signup.erb [...]
         Test:       test/unit/test/unit/notifications_test.rb
         Fixtures:   test/fixtures/notifications/signup [...]
-
diff --git a/railties/lib/rails_generator/generators/components/migration/USAGE b/railties/lib/rails_generator/generators/components/migration/USAGE
index 749076e946..152e2abdd6 100644
--- a/railties/lib/rails_generator/generators/components/migration/USAGE
+++ b/railties/lib/rails_generator/generators/components/migration/USAGE
@@ -1,14 +1,10 @@
 Description:
-    The migration generator creates a stub for a new database migration.
-
-    The generator takes a migration name as its argument.  The migration name may be
-    given in CamelCase or under_score.
-
-    The generator creates a migration class in db/migrate prefixed by its number
-    in the queue.
+    Stubs out a new database migration. Pass the migration name, either
+    CamelCased or under_scored, as an argument. A migration class is generated
+    in db/migrate prefixed by the latest migration number.
 
 Example:
-    ./script/generate migration AddSslFlag
+    `./script/generate migration AddSslFlag`
 
-    With 4 existing migrations, this will create an AddSslFlag migration in the
-    file db/migrate/005_add_ssl_flag.rb
\ No newline at end of file
+    With 4 existing migrations, this creates the AddSslFlag migration in
+    db/migrate/005_add_ssl_flag.rb
diff --git a/railties/lib/rails_generator/generators/components/model/USAGE b/railties/lib/rails_generator/generators/components/model/USAGE
index b93cf73716..24b03b4d4a 100644
--- a/railties/lib/rails_generator/generators/components/model/USAGE
+++ b/railties/lib/rails_generator/generators/components/model/USAGE
@@ -1,27 +1,27 @@
 Description:
-    The model generator creates stubs for a new model.
+    Stubs out a new model. Pass the model name, either CamelCased or
+    under_scored, and an optional list of attribute pairs as arguments.
 
-    The generator takes a model name as its argument.  The model name may be given in CamelCase or under_score and
-    should not be suffixed with 'Model'.
+    Attribute pairs are column_name:sql_type arguments specifying the
+    model's attributes. Timestamps are added by default, so you don't have to
+    specify them by hand as 'created_at:datetime updated_at:datetime'.
 
-    As additional parameters, the generator will take attribute pairs described by name and type. These attributes will
-    be used to prepopulate the migration to create the table for the model and give you a set of predefined fixture.  By
-    default, created_at and updated_at timestamps are added to migration for you, so you needn't specify them by hand.
-    You don't have to think up all attributes up front, but it's a good idea of adding just the baseline of what's
-    needed to start really working with the resource.
+    You don't have to think up every attribute up front, but it helps to
+    sketch out a few so you can start working with the model immediately.
 
-    The generator creates a model class in app/models, a test suite in test/unit, test fixtures in
-    test/fixtures/singular_name.yml, and a migration in db/migrate.
+    This generates a model class in app/models, a unit test in test/unit,
+    a test fixture in test/fixtures/singular_name.yml, and a migration in
+    db/migrate.
 
 Examples:
-    ./script/generate model account
+    `./script/generate model account`
 
-        This will create an Account model:
+        creates an Account model, test, fixture, and migration:
             Model:      app/models/account.rb
             Test:       test/unit/account_test.rb
             Fixtures:   test/fixtures/accounts.yml
             Migration:  db/migrate/XXX_add_accounts.rb
 
-    ./script/generate model post title:string body:text published:boolean
+    `./script/generate model post title:string body:text published:boolean`
 
-        Creates post model with predefined attributes.
+        creates a Post model with a string title, text body, and published flag.
diff --git a/railties/lib/rails_generator/generators/components/observer/USAGE b/railties/lib/rails_generator/generators/components/observer/USAGE
index 8abaf3678f..a5d744a3c2 100644
--- a/railties/lib/rails_generator/generators/components/observer/USAGE
+++ b/railties/lib/rails_generator/generators/components/observer/USAGE
@@ -1,15 +1,13 @@
 Description:
-    The observer generator creates stubs for a new observer.
+    Stubs out a new observer. Pass the observer name, either CamelCased or
+    under_scored, as an argument.
 
-    The generator takes a observer name as its argument.  The observer name may be
-    given in CamelCase or under_score and should not be suffixed with 'Observer'.
-
-    The generator creates a observer class in app/models and a test suite in
+    The generator creates an observer class in app/models and a unit test in
     test/unit.
 
 Example:
-    ./script/generate observer Account
+    `./script/generate observer Account`
 
-    This will create an Account observer:
+    creates an Account observer and unit test:
         Observer:   app/models/account_observer.rb
         Test:       test/unit/account_observer_test.rb
diff --git a/railties/lib/rails_generator/generators/components/plugin/USAGE b/railties/lib/rails_generator/generators/components/plugin/USAGE
index f033c81442..d2ecfc2d59 100644
--- a/railties/lib/rails_generator/generators/components/plugin/USAGE
+++ b/railties/lib/rails_generator/generators/components/plugin/USAGE
@@ -1,19 +1,15 @@
 Description:
-    The plugin generator creates stubs for a new plugin.
+    Stubs out a new plugin. Pass the plugin name, either CamelCased or
+    under_scored, as an argument. Pass --with-generator to add an example
+    generator also.
 
-    The generator takes a plugin name as its argument.  The plugin name may be
-    given in CamelCase or under_score and should not be suffixed with 'Plugin'.
-
-    The generator creates a plugin directory in vendor/plugins that includes
-    both init.rb and README files as well as lib, task, and test directories.
-
-    It's also possible to generate stub files for a generator to go with the 
-    plugin by using --with-generator
+    This creates a plugin in vendor/plugins including an init.rb and README
+    as well as standard lib, task, and test directories.
 
 Example:
-    ./script/generate plugin BrowserFilters
+    `./script/generate plugin BrowserFilters`
 
-    This will create:
+    creates a standard browser_filters plugin:
         vendor/plugins/browser_filters/README
         vendor/plugins/browser_filters/init.rb
         vendor/plugins/browser_filters/install.rb
@@ -23,13 +19,7 @@ Example:
 
     ./script/generate plugin BrowserFilters --with-generator
 
-    This will create:
-        vendor/plugins/browser_filters/README
-        vendor/plugins/browser_filters/init.rb
-        vendor/plugins/browser_filters/install.rb
-        vendor/plugins/browser_filters/lib/browser_filters.rb
-        vendor/plugins/browser_filters/test/browser_filters_test.rb
-        vendor/plugins/browser_filters/tasks/browser_filters_tasks.rake
+    creates a browser_filters generator also:
         vendor/plugins/browser_filters/generators/browser_filters/browser_filters_generator.rb
         vendor/plugins/browser_filters/generators/browser_filters/USAGE
         vendor/plugins/browser_filters/generators/browser_filters/templates/
diff --git a/railties/lib/rails_generator/generators/components/resource/USAGE b/railties/lib/rails_generator/generators/components/resource/USAGE
index d396775a41..83cc9d7654 100644
--- a/railties/lib/rails_generator/generators/components/resource/USAGE
+++ b/railties/lib/rails_generator/generators/components/resource/USAGE
@@ -1,33 +1,23 @@
 Description:
-    The resource generator creates an empty model, controller, and functional
-    test suitable for a RESTful, resource-oriented application.
+    Stubs out a new resource including an empty model and controller suitable
+    for a restful, resource-oriented application. Pass the singular model name,
+    either CamelCased or under_scored, as the first argument, and an optional
+    list of attribute pairs.
 
-    The generator takes the name of the model as its first argument. This
-    model name is then pluralized to get the controller name. So "resource
-    post" will generate a Post model and a PostsController and will be
-    intended for URLs like /posts and /posts/45.
+    Attribute pairs are column_name:sql_type arguments specifying the
+    model's attributes. Timestamps are added by default, so you don't have to
+    specify them by hand as 'created_at:datetime updated_at:datetime'.
 
-    As additional parameters, the generator will take attribute pairs
-    described by name and type. These attributes will be used to
-    prepopulate the migration to create the table for the model. For
-    example, "resource post title:string body:text published:boolean" will
-    give you a Post model with those three attributes.
+    You don't have to think up every attribute up front, but it helps to
+    sketch out a few so you can start working with the resource immediately.
 
-    By default, created_at and updated_at timestamps are added to migration
-    for you, so you needn't specify them by hand.
+    This creates a model, controller, tests and fixtures for both, and the
+    corresponding map.resources declaration in config/routes.rb
 
-    You don't have to think up all attributes up front, but it's a good
-    idea of adding just the baseline of what's needed to start really
-    working with the resource.
-
-    The generator also adds an appropriate map.resources declaration to
-    your config/routes.rb file, hooking up the rules that'll point URLs to
-    this new resource.
-
-    Unlike the scaffold generator, the resource generator does not
-    create views or add any methods to the generated controller.
+    Unlike the scaffold generator, the resource generator does not create
+    views or add any methods to the generated controller.
 
 Examples:
-    ./script/generate resource post # no attributes
-    ./script/generate resource post title:string body:text published:boolean
-    ./script/generate resource purchase order_id:integer amount:decimal
+    `./script/generate resource post` # no attributes
+    `./script/generate resource post title:string body:text published:boolean`
+    `./script/generate resource purchase order_id:integer amount:decimal`
diff --git a/railties/lib/rails_generator/generators/components/scaffold/USAGE b/railties/lib/rails_generator/generators/components/scaffold/USAGE
index ecbb98300d..a0e4baea08 100644
--- a/railties/lib/rails_generator/generators/components/scaffold/USAGE
+++ b/railties/lib/rails_generator/generators/components/scaffold/USAGE
@@ -1,40 +1,25 @@
 Description:
-    The scaffold resource generator creates a model, a controller, and a
-    set of templates that's ready to use as the starting point for your
-    REST-like, resource-oriented application. This basically means that it
-    follows a set of conventions to exploit the full set of HTTP verbs
-    (GET/POST/PUT/DELETE) and is prepared for multi-client access (like one
-    view for HTML, one for an XML API, one for ATOM, etc). Everything comes
-    with sample unit and functional tests as well.
+    Scaffolds an entire resource, from model and migration to controller and
+    views, along with a full test suite. The resource is ready to use as a
+    starting point for your restful, resource-oriented application.
 
-    The generator takes the name of the model as its first argument. This
-    model name is then pluralized to get the controller name. So
-    "scaffold post" will generate a Post model and a
-    PostsController and will be intended for URLs like /posts and
-    /posts/45.
+    Pass the name of the model, either CamelCased or under_scored, as the first
+    argument, and an optional list of attribute pairs.
 
-    As additional parameters, the generator will take attribute pairs
-    described by name and type. These attributes will be used to
-    prepopulate the migration to create the table for the model and to give
-    you a set of templates for the view. For example, "scaffold post
-    title:string body:text published:boolean" will give you a model with
-    those three attributes, forms to create and edit those models from,
-    and an index that'll list them all.
+    Attribute pairs are column_name:sql_type arguments specifying the
+    model's attributes. Timestamps are added by default, so you don't have to
+    specify them by hand as 'created_at:datetime updated_at:datetime'.
 
-    By default, created_at and updated_at timestamps are added to migration
-    for you, so you needn't specify them by hand.
+    You don't have to think up every attribute up front, but it helps to
+    sketch out a few so you can start working with the resource immediately.
 
-    You don't have to think up all attributes up front, but it's a good
-    idea of adding just the baseline of what's needed to start really
-    working with the resource.
-
-    The generator also adds a declaration to your config/routes.rb file
-    to hook up the rules that'll point URLs to this new resource. If you
-    create a resource like "scaffold post", it will add
-    "map.resources :posts" (notice the plural form) in the routes file,
-    making your new resource accessible from /posts.
+    For example, `scaffold post title:string body:text published:boolean`
+    gives you a model with those three attributes, a controller that handles
+    the create/show/update/destroy, forms to create and edit your posts, and
+    an index that lists them all, as well as a map.resources :posts
+    declaration in config/routes.rb.
 
 Examples:
-    ./script/generate scaffold post # no attributes, view will be anemic
-    ./script/generate scaffold post title:string body:text published:boolean
-    ./script/generate scaffold purchase order_id:integer amount:decimal
+    `./script/generate scaffold post` # no attributes, view will be anemic
+    `./script/generate scaffold post title:string body:text published:boolean`
+    `./script/generate scaffold purchase order_id:integer amount:decimal`
diff --git a/railties/lib/rails_generator/generators/components/session_migration/USAGE b/railties/lib/rails_generator/generators/components/session_migration/USAGE
index 3234a4efd0..87117a3cb6 100644
--- a/railties/lib/rails_generator/generators/components/session_migration/USAGE
+++ b/railties/lib/rails_generator/generators/components/session_migration/USAGE
@@ -1,15 +1,10 @@
 Description:
-    The session table migration generator creates a migration for adding a session table 
-    used by CGI::Session::ActiveRecordStore.
-
-    The generator takes a migration name as its argument.  The migration name may be
-    given in CamelCase or under_score.
-
-    The generator creates a migration class in db/migrate prefixed by its number
-    in the queue.
+    Creates a migration to add the sessions table used by the Active Record
+    session store. Pass the migration name, either CamelCased or under_scored,
+    as an argument.
 
 Example:
-    ./script/generate session_migration AddSessionTable
+    `./script/generate session_migration CreateSessionTable`
 
-    With 4 existing migrations, this will create an AddSessionTable migration in the
-    file db/migrate/005_add_session_table.rb
\ No newline at end of file
+    With 4 existing migrations, this creates the AddSessionTable migration
+    in db/migrate/005_add_session_table.rb
diff --git a/railties/lib/rails_generator/generators/components/web_service/USAGE b/railties/lib/rails_generator/generators/components/web_service/USAGE
index d3e45b7fef..1b9192f7b1 100644
--- a/railties/lib/rails_generator/generators/components/web_service/USAGE
+++ b/railties/lib/rails_generator/generators/components/web_service/USAGE
@@ -1,28 +1,24 @@
 Description:
-    The web service generator creates the controller and API definition for 
-    a web service.
+    Stubs out the controller and API for a new web service using the deprecated
+    Action Web Service framework. Pass the web service name, either CamelCased
+    or under_scored, and a list of API methods as arguments. To create a web
+    service within a module, use a path like 'module_name/web_service_name'.
 
-    The generator takes a web service name and a list of API methods as arguments.
-    The web service name may be given in CamelCase or under_score and should
-    contain no extra suffixes.  To create a web service within a
-    module, specify the web service name as 'module/webservice'.
-
-    The generator creates a controller class in app/controllers, an API definition
-    in app/apis, and a functional test suite in test/functional.
+    This generates a controller in app/controllers, an API definition
+    in app/apis, and functional tests in test/functional.
 
 Example:
-    ./script/generate web_service User add edit list remove
+    `./script/generate web_service User add edit list remove`
 
-    User web service.
+    creates the User controller, API, and functional test:
         Controller: app/controllers/user_controller.rb
         API:        app/apis/user_api.rb
         Test:       test/functional/user_api_test.rb
 
 Modules Example:
-    ./script/generate web_service 'api/registration' register renew
+    `./script/generate web_service 'api/registration' register renew`
 
-    Registration web service.
+    creates the Registration controller, API, and functional test:
         Controller: app/controllers/api/registration_controller.rb
         API:        app/apis/api/registration_api.rb
         Test:       test/functional/api/registration_api_test.rb
-