From fd20653f5abeab30b8dbf8a7b41f7b39893cabc0 Mon Sep 17 00:00:00 2001
From: Steve Polito <stevepolito@hey.com>
Date: Sun, 21 Apr 2024 06:45:57 -0400
Subject: [PATCH] Generators: Update descriptions

Follow-up to #1187
---
 .../suspenders/accessibility_generator.rb     |  7 ++++-
 .../suspenders/advisories_generator.rb        |  6 ++---
 lib/generators/suspenders/ci_generator.rb     |  5 +++-
 lib/generators/suspenders/email_generator.rb  |  8 ++++--
 .../suspenders/factories_generator.rb         | 18 ++++++-------
 .../suspenders/inline_svg_generator.rb        |  6 ++++-
 lib/generators/suspenders/jobs_generator.rb   |  8 +++++-
 lib/generators/suspenders/lint_generator.rb   | 19 +++++++++++++-
 .../suspenders/prerequisites_generator.rb     |  2 +-
 lib/generators/suspenders/rake_generator.rb   |  9 +++++--
 lib/generators/suspenders/setup_generator.rb  |  6 +----
 lib/generators/suspenders/styles_generator.rb | 20 ++++++++++++--
 lib/generators/suspenders/tasks_generator.rb  |  4 +--
 .../suspenders/testing_generator.rb           | 26 ++++++++++++++++++-
 lib/generators/suspenders/views_generator.rb  | 13 ++++++++--
 15 files changed, 122 insertions(+), 35 deletions(-)

diff --git a/lib/generators/suspenders/accessibility_generator.rb b/lib/generators/suspenders/accessibility_generator.rb
index 003ac817d..44c415af0 100644
--- a/lib/generators/suspenders/accessibility_generator.rb
+++ b/lib/generators/suspenders/accessibility_generator.rb
@@ -4,7 +4,12 @@ class AccessibilityGenerator < Rails::Generators::Base
       include Suspenders::Generators::APIAppUnsupported
 
       desc <<~MARKDOWN
-        Installs capybara_accessibility_audit and capybara_accessible_selectors"
+        Uses [capybara_accessibility_audit][] and
+        [capybara_accessible_selectors][] to encourage and enforce accessibility best
+        practices.
+
+        [capybara_accessibility_audit]: https://github.com/thoughtbot/capybara_accessibility_audit
+        [capybara_accessible_selectors]: https://github.com/citizensadvice/capybara_accessible_selectors
       MARKDOWN
 
       def add_capybara_gems
diff --git a/lib/generators/suspenders/advisories_generator.rb b/lib/generators/suspenders/advisories_generator.rb
index 2d27fca50..82c5100a2 100644
--- a/lib/generators/suspenders/advisories_generator.rb
+++ b/lib/generators/suspenders/advisories_generator.rb
@@ -3,10 +3,10 @@ module Generators
     class AdvisoriesGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/advisories", __FILE__)
       desc <<~MARKDOWN
-        Show security advisories during development.
+        Uses [bundler-audit][] to update the local security database and show
+        any relevant issues with the app's dependencies via a Rake task.
 
-        Uses the `bundler-audit` gem to update the local security database and
-        show any relevant issues with the app's dependencies via a Rake task.
+        [bundler-audit]: https://github.com/rubysec/bundler-audit
       MARKDOWN
 
       def add_bundler_audit
diff --git a/lib/generators/suspenders/ci_generator.rb b/lib/generators/suspenders/ci_generator.rb
index 4204b38d0..51e7d01b5 100644
--- a/lib/generators/suspenders/ci_generator.rb
+++ b/lib/generators/suspenders/ci_generator.rb
@@ -6,7 +6,10 @@ class CiGenerator < Rails::Generators::Base
 
       source_root File.expand_path("../../templates/ci", __FILE__)
       desc <<~MARKDOWN
-        Creates CI files for GitHub Actions
+        Uses [GitHub Actions][] for CI, and [Dependabot][] for dependency updates.
+
+        [GitHub Actions]: https://docs.github.com/en/actions
+        [Dependabot]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot
       MARKDOWN
 
       def ci_files
diff --git a/lib/generators/suspenders/email_generator.rb b/lib/generators/suspenders/email_generator.rb
index 7883b692a..f46536acc 100644
--- a/lib/generators/suspenders/email_generator.rb
+++ b/lib/generators/suspenders/email_generator.rb
@@ -3,13 +3,17 @@ module Generators
     class EmailGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/email", __FILE__)
       desc <<~MARKDOWN
-        Intercepts emails in non-production environments by setting `INTERCEPTOR_ADDRESSES`.
+        [Intercept][] emails in non-production environments by setting `INTERCEPTOR_ADDRESSES`.
 
         ```sh
         INTERCEPTOR_ADDRESSES="user_1@example.com,user_2@example.com" bin/rails s
         ```
 
-        Configures `default_url_options` in `test` and `development`.
+        Configuration can be found at `config/initializers/email_interceptor.rb`.
+
+        Interceptor can be found at `app/mailers/email_interceptor.rb`.
+
+        [Intercept]: https://guides.rubyonrails.org/action_mailer_basics.html#intercepting-emails
       MARKDOWN
 
       def create_email_interceptor
diff --git a/lib/generators/suspenders/factories_generator.rb b/lib/generators/suspenders/factories_generator.rb
index 855b82984..48fb06a39 100644
--- a/lib/generators/suspenders/factories_generator.rb
+++ b/lib/generators/suspenders/factories_generator.rb
@@ -5,18 +5,16 @@ class FactoriesGenerator < Rails::Generators::Base
 
       source_root File.expand_path("../../templates/factories", __FILE__)
       desc <<~MARKDOWN
-        Build test data with clarity and ease.
+        Uses [FactoryBot][] as an alternative to [Fixtures][] to help you define
+        dummy and test data for your test suite. The `create`, `build`, and
+        `build_stubbed` class methods are directly available to all tests.
 
-        This uses FactoryBot to help you define dummy and test data for your test
-        suite. The `create`, `build`, and `build_stubbed` class methods are directly
-        available to all tests.
+        Place FactoryBot definitions in `spec/factories.rb`, at least until it
+        grows unwieldy. This helps reduce confusion around circular dependencies and
+        makes it easy to jump between definitions.
 
-        We recommend putting FactoryBot definitions in one `spec/factories.rb` (or
-        `test/factories`) file, at least until it grows unwieldy. This helps reduce
-        confusion around circular dependencies and makes it easy to jump between
-        definitions.
-
-        Supports the default test suite and RSpec.
+        [FactoryBot]: https://github.com/thoughtbot/factory_bot
+        [Fixtures]: https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures
       MARKDOWN
 
       def add_factory_bot
diff --git a/lib/generators/suspenders/inline_svg_generator.rb b/lib/generators/suspenders/inline_svg_generator.rb
index 0d530aaef..0728e4276 100644
--- a/lib/generators/suspenders/inline_svg_generator.rb
+++ b/lib/generators/suspenders/inline_svg_generator.rb
@@ -4,7 +4,11 @@ class InlineSvgGenerator < Rails::Generators::Base
       include Suspenders::Generators::APIAppUnsupported
       source_root File.expand_path("../../templates/inline_svg", __FILE__)
       desc <<~MARKDOWN
-        Render SVG images inline, as a potential performance improvement for the viewer.
+        Uses [inline_svg][] for embedding SVG documents into views.
+
+        Configuration can be found at `config/initializers/inline_svg.rb`
+
+        [inline_svg]: https://github.com/jamesmartin/inline_svg
       MARKDOWN
 
       def add_inline_svg_gem
diff --git a/lib/generators/suspenders/jobs_generator.rb b/lib/generators/suspenders/jobs_generator.rb
index c9cfc1a70..2f8af96af 100644
--- a/lib/generators/suspenders/jobs_generator.rb
+++ b/lib/generators/suspenders/jobs_generator.rb
@@ -2,7 +2,13 @@ module Suspenders
   module Generators
     class JobsGenerator < Rails::Generators::Base
       desc <<~MARKDOWN
-        Installs Sidekiq for background job processing.
+        Uses [Sidekiq][] for [background job][] processing.
+
+        Configures the `test` environment to use the [inline][] adapter.
+
+        [Sidekiq]: https://github.com/sidekiq/sidekiq
+        [background job]: https://guides.rubyonrails.org/active_job_basics.html
+        [inline]: https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/InlineAdapter.html
       MARKDOWN
 
       def add_sidekiq_gem
diff --git a/lib/generators/suspenders/lint_generator.rb b/lib/generators/suspenders/lint_generator.rb
index 20d2f791f..0ee6500a6 100644
--- a/lib/generators/suspenders/lint_generator.rb
+++ b/lib/generators/suspenders/lint_generator.rb
@@ -5,7 +5,24 @@ class LintGenerator < Rails::Generators::Base
 
       source_root File.expand_path("../../templates/lint", __FILE__)
       desc <<~MARKDOWN
-        Creates a holistic linting solution that covers JavaScript, CSS, Ruby and ERB.
+        Uses [@thoughtbot/eslint-config][] for JavaScript linting.
+        Uses [@thoughtbot/stylelint-config][] for CSS linting.
+        Uses [prettier][] for additional linting.
+        Uses [better_html][], [erb_lint][], and [erblint-github][] for ERB linting.
+        Uses [standard][] for Ruby linting.
+
+        Run `yarn lint` to lint front-end code.
+        Run `yarn fix:prettier` to automatically fix prettier violations.
+        Run `bin/rails standard` to lint ERB and Ruby code.
+        Run `bundle exec standardrb --fix` to fix standard violations.
+
+        [@thoughtbot/eslint-config]: https://github.com/thoughtbot/eslint-config
+        [@thoughtbot/stylelint-config]: https://github.com/thoughtbot/stylelint-config
+        [prettier]: https://prettier.io
+        [better_html]: https://github.com/Shopify/better-html
+        [erb_lint]: https://github.com/Shopify/erb-lint
+        [erblint-github]: https://github.com/github/erblint-github
+        [standard]: https://github.com/standardrb/standard
       MARKDOWN
 
       def check_package_json
diff --git a/lib/generators/suspenders/prerequisites_generator.rb b/lib/generators/suspenders/prerequisites_generator.rb
index 59f84d78d..e96fb1d21 100644
--- a/lib/generators/suspenders/prerequisites_generator.rb
+++ b/lib/generators/suspenders/prerequisites_generator.rb
@@ -4,7 +4,7 @@ class PrerequisitesGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/prerequisites", __FILE__)
 
       desc <<~MARKDOWN
-        Configures prerequisites. Currently Node.
+        Creates `.node-version` file set to the current LTS version.
       MARKDOWN
 
       def node_version
diff --git a/lib/generators/suspenders/rake_generator.rb b/lib/generators/suspenders/rake_generator.rb
index 7e84033e3..75354df35 100644
--- a/lib/generators/suspenders/rake_generator.rb
+++ b/lib/generators/suspenders/rake_generator.rb
@@ -3,8 +3,13 @@ module Generators
     class RakeGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/rake", __FILE__)
       desc <<~MARKDOWN
-        Configures the default Rake task to audit and lint the codebase with
-        `bundler-audit` and `standard`, in addition to running the test suite.
+        Adds default Raketask wich is a wrapper for `suspenders:rake`.
+
+        This will do the following:
+
+          - Run the test suite.
+          - Run a Ruby and ERB linter.
+          - Scan the Ruby codebase for any dependecy vulnerabilities.
       MARKDOWN
 
       def configure_default_rake_task
diff --git a/lib/generators/suspenders/setup_generator.rb b/lib/generators/suspenders/setup_generator.rb
index 3f69e499e..7ab6fc79a 100644
--- a/lib/generators/suspenders/setup_generator.rb
+++ b/lib/generators/suspenders/setup_generator.rb
@@ -3,11 +3,7 @@ module Generators
     class SetupGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/setup", __FILE__)
       desc <<~MARKDOWN
-        A holistic setup script.
-
-        ```sh
-        bin/setup
-        ```
+        Run `bin/setup` to install dependencies and seed development data.
       MARKDOWN
 
       def replace_bin_setup
diff --git a/lib/generators/suspenders/styles_generator.rb b/lib/generators/suspenders/styles_generator.rb
index cdc5feef5..340e71ab5 100644
--- a/lib/generators/suspenders/styles_generator.rb
+++ b/lib/generators/suspenders/styles_generator.rb
@@ -5,9 +5,25 @@ class StylesGenerator < Rails::Generators::Base
 
       source_root File.expand_path("../../templates/styles", __FILE__)
       desc <<~MARKDOWN
-        Configures application to use PostCSS via cssbundling-rails.
+        Uses [PostCSS][] via [cssbundling-rails][].
+        Uses [modern-normalize][] to normalize browsers' default style.
 
-        Adds modern-normalize, and style sheet structure.
+        Configuration can be found at `postcss.config.js`.
+
+        Adds the following stylesheet structure.
+
+        ```css
+        app/assets/stylesheet/base.css
+        app/assets/stylesheet/components.css
+        app/assets/stylesheet/utilities.css
+        ```
+
+        Adds `app/assets/static` so that [postcss-url][] has a directory to copy
+        assets to.
+
+        [PostCSS]: https://postcss.org
+        [cssbundling-rails]: https://github.com/rails/cssbundling-rails
+        [modern-normalize]: https://github.com/sindresorhus/modern-normalize
       MARKDOWN
 
       def add_cssbundling_rails_gem
diff --git a/lib/generators/suspenders/tasks_generator.rb b/lib/generators/suspenders/tasks_generator.rb
index b8b9a8a7b..924879e7c 100644
--- a/lib/generators/suspenders/tasks_generator.rb
+++ b/lib/generators/suspenders/tasks_generator.rb
@@ -3,9 +3,9 @@ module Generators
     class TasksGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/tasks", __FILE__)
       desc <<~MARKDOWN
-        Creates local Rake tasks for development
+        Creates `lib/tasks/dev.rake` which contains the following tasks:
 
-        bin/rails dev:prime # Sample data for local development environment
+        `bin/rails dev:prime` which loads sample data for local development.
       MARKDOWN
 
       def create_dev_rake
diff --git a/lib/generators/suspenders/testing_generator.rb b/lib/generators/suspenders/testing_generator.rb
index cc862055a..e9bdac021 100644
--- a/lib/generators/suspenders/testing_generator.rb
+++ b/lib/generators/suspenders/testing_generator.rb
@@ -3,7 +3,31 @@ module Generators
     class TestingGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/testing", __FILE__)
       desc <<~MARKDOWN
-        Set up the project for an in-depth test-driven development workflow.
+        Uses [RSpec][] and [RSpec Rails][] in favor of the [default test suite][].
+
+        The test suite can be run with `bin/rails spec`.
+
+        Configuration can be found in the following files:
+
+        ```
+        spec/rails_helper.rb
+        spec/spec_helper.rb
+        spec/support/action_mailer.rb
+        spec/support/driver.rb
+        spec/support/i18n.rb
+        spec/support/should_matchers.rb
+        ```
+
+        Uses [action_dispatch-testing-integration-capybara][] to introduce Capybara assertions into Request specs.
+        Uses [should-matchers][] for simple one-liner tests for common Rails functionality.
+        Uses [webmock][] for stubbing and setting expectations on HTTP requests in Ruby.
+
+        [RSpec]: http://rspec.info
+        [RSpec Rails]: https://github.com/rspec/rspec-rails
+        [default test suite]: https://guides.rubyonrails.org/testing.html
+        [action_dispatch-testing-integration-capybara]: https://github.com/thoughtbot/action_dispatch-testing-integration-capybara
+        [should-matchers]: https://github.com/thoughtbot/shoulda-matchers
+        [webmock]: https://github.com/bblimke/webmock
       MARKDOWN
 
       def add_gems
diff --git a/lib/generators/suspenders/views_generator.rb b/lib/generators/suspenders/views_generator.rb
index 227ce3b75..9ba991492 100644
--- a/lib/generators/suspenders/views_generator.rb
+++ b/lib/generators/suspenders/views_generator.rb
@@ -3,10 +3,19 @@ module Generators
     class ViewsGenerator < Rails::Generators::Base
       include Suspenders::Generators::APIAppUnsupported
 
+      source_root File.expand_path("../../templates/views", __FILE__)
       desc <<~MARKDOWN
-        Configures flash messages, page titles and the document lang. Disables Turbo's InstantClick.
+        - A [partial][] for [flash messages][] is located in `app/views/application/_flashes.html.erb`.
+        - Sets [lang][] attribute on `<html>` element to `en` via `I18n.local`.
+        - Dynamically sets `<title>` via the [title][] gem.
+        - Disables Turbo's [Prefetch][] in an effort to reduce unnecessary network requests.
+
+        [partial]: https://guides.rubyonrails.org/layouts_and_rendering.html#using-partials
+        [flash messsages]: https://guides.rubyonrails.org/action_controller_overview.html#the-flash
+        [lang]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang
+        [title]: https://github.com/calebhearth/title
+        [Prefetch]: https://turbo.hotwired.dev/handbook/drive#prefetching-links-on-hover
       MARKDOWN
-      source_root File.expand_path("../../templates/views", __FILE__)
 
       def install_gems
         gem "title"