Copy edit to lib/mix/tasks/phx.gen.html.ex (#5675)

lib/mix/tasks/phx.gen.html.ex

@@ -2,54 +2,64 @@ defmodule Mix.Tasks.Phx.Gen.Html do
   @shortdoc "Generates context and controller for an HTML resource"
 
   @moduledoc """
-  Generates controller, HTML views, and context for an HTML resource.
+  Generates controller with view, templates, schema and context for an HTML resource.
 
       mix phx.gen.html Accounts User users name:string age:integer
 
-  The first argument is the context module followed by the schema module
-  and its plural name (used as the schema table name).
+  The first argument, `Accounts`, is the resource's context.
+  A context is an Elixir module that serves as an API boundary for closely related resources.
 
-  The context is an Elixir module that serves as an API boundary for
-  the given resource. A context often holds many related resources.
-  Therefore, if the context already exists, it will be augmented with
-  functions for the given resource.
+  The second argument, `User`, is the resource's schema.
+  A schema is an Elixir module responsible for mapping database fields into an Elixir struct.
+  The `User` schema above specifies two fields with their respective colon-delimited data types:
+  `name:string` and `age:integer`. See `mix phx.gen.schema` for more information on attributes.
 
   > Note: A resource may also be split
   > over distinct contexts (such as `Accounts.User` and `Payments.User`).
 
-  The schema is responsible for mapping the database fields into an
-  Elixir struct. It is followed by an optional list of attributes,
-  with their respective names and types. See `mix phx.gen.schema`
-  for more information on attributes.
+  This generator adds the following files to `lib/`:
 
-  Overall, this generator will add the following files to `lib/`:
+    * a controller in `lib/my_app_web/controllers/user_controller.ex`
+    * default CRUD HTML templates in `lib/my_app_web/controllers/user_html`
+    * an HTML view collocated with the controller in `lib/my_app_web/controllers/user_html.ex`
+    * a schema in `lib/my_app/accounts/user.ex`, with an `users` table
+    * a context module in `lib/my_app/accounts.ex` for the accounts API
 
-    * a context module in `lib/app/accounts.ex` for the accounts API
-    * a schema in `lib/app/accounts/user.ex`, with an `users` table
-    * a controller in `lib/app_web/controllers/user_controller.ex`
-    * an HTML view collocated with the controller in `lib/app_web/controllers/user_html.ex`
-    * default CRUD templates in `lib/app_web/controllers/user_html`
+  Additionally, this generator creates the following files:
 
-  ## The context app
+    * a migration for the schema in `priv/repo/migrations`
+    * a controller test module in `test/my_app/controllers/user_controller_test.exs`
+    * a context test module in `test/my_app/accounts_test.exs`
+    * a context test helper module in `test/support/fixtures/accounts_fixtures.ex`
 
-  A migration file for the repository and test files for the context and
-  controller features will also be generated.
+  If the context already exists, this generator injects functions for the given resource into
+  the context, context test, and context test helper modules.
 
-  The location of the web files (controllers, HTML views, templates, etc) in an
-  umbrella application will vary based on the `:context_app` config located
-  in your applications `:generators` configuration. When set, the Phoenix
-  generators will generate web files directly in your lib and test folders
-  since the application is assumed to be isolated to web specific functionality.
-  If `:context_app` is not set, the generators will place web related lib
-  and test files in a `web/` directory since the application is assumed
-  to be handling both web and domain specific functionality.
-  Example configuration:
+  ## Umbrella app configuration
 
-      config :my_app_web, :generators, context_app: :my_app
+  By default, Phoenix injects both web and domain specific functionality into the same
+  application. When using umbrella applications, those concerns are typically broken
+  into two separate apps, your context application - let's call it `my_app` - and its web
+  layer, which Phoenix assumes to be `my_app_web`.
+
+  You can teach Phoenix to use this style via the `:context_app` configuration option
+  in your `my_app_umbrella/config/config.exs`:
+
+      config :my_app_web,
+        ecto_repos: [Stuff.Repo],
+        generators: [context_app: :my_app]
 
   Alternatively, the `--context-app` option may be supplied to the generator:
 
-      mix phx.gen.html Sales User users --context-app warehouse
+      mix phx.gen.html Sales User users --context-app my_app
+
+  If you delete the `:context_app` configuration option, Phoenix will automatically put generated web files in
+  `my_app_umbrella/apps/my_app_web_web`.
+
+  If you change the value of `:context_app` to `:new_value`, `my_app_umbrella/apps/new_value_web`
+  must already exist or you will get the following error:
+
+     ** (Mix) no directory for context_app :new_value found in my_app_web's deps.
 
   ## Web namespace