Update messages for new sandbox resume command (#271)

* update messages for "sf env create sandbox"

* update command to take new flag descriptions

* edit messages for "sf env resume sandbox"

* update command with changes I made to messages

* edit

* add pete's comment

messages/create.sandbox.md

@@ -68,13 +68,21 @@ Type of sandbox license.
 
 Number of minutes to wait for the sandbox org to be ready.
 
+# flags.wait.description
+
+If the command continues to run after the wait period, the CLI returns control of the terminal to you and displays the "sf env resume sandbox" command you run to check the status of the create.  The displayed command includes the job ID for the running sandbox creation. 
+
 # flags.poll-interval.summary
 
 Number of seconds to wait between retries.
 
 # flags.async.summary
 
-Don't wait for the sandbox create to complete.
+Request the sandbox creation, but don't wait for it to complete.
+
+# flags.async.description
+
+The command immediately displays the job ID and returns control of the terminal to you. This way, you can continue to use the CLI. To check the status of the sandbox creation, run "sf env resume sandbox".
 
 # flags.noPrompt.summary
 

messages/resume.sandbox.md

@@ -1,36 +1,38 @@
 # summary
 
-Check sandbox create status and complete authorization, if possible.
+Check the status of a sandbox creation, and log in to it if it's ready.
 
 # description
 
-Sandbox creation can take a long time, so we check the status of the sandbox creation using <%= config.bin %> <%= command.id %>.
+Sandbox creation can take a long time. If the original "sf env create sandbox" command either times out, or you specified the --async flag, the command displays a job ID. Use this job ID to check whether the sandbox creation is complete, and if it is, the command then logs into it.
+
+You can also use the sandbox name to check the status or the --use-most-recent flag to use the job ID of the most recent sandbox creation.
 
 # examples
 
-- Check the status of sandbox creation using the sandbox name.
+- Check the status of a sandbox creation using its name and specify a production org with alias "prodOrg":
 
-  <%= config.bin %> <%= command.id %> --name <sandbox name> [--target-org <production org username>]
+  <%= config.bin %> <%= command.id %> --name mysandbox --target-org prodOrg
 
-- Check the status of sandbox creation using the sandbox request job id.
+- Check the status using the job ID:
 
-  <%= config.bin %> <%= command.id %> --job-id 0GRxxxxxxxxxxxxxxx [--target-org <production org username>]
+  <%= config.bin %> <%= command.id %> --job-id 0GRxxxxxxxx
 
-- Check the status of sandbox creation using the latest sandbox request.
+- Check the status of the most recent sandbox create request:
 
-  <%= config.bin %> <%= command.id %> --use-latest-request
+  <%= config.bin %> <%= command.id %> --use-most-recent
 
 # flags.setDefault.summary
 
 Set the sandbox org as your default org.
 
 # flags.id.summary
 
-The sandbox process object Id.
+Job ID of the incomplete sandbox creation that you want to check the status of.
 
 # flags.id.description
 
-The sandbox process object Id.
+The job ID is valid for 24 hours after you start the sandbox creation.
 
 # flags.alias.summary
 
@@ -52,30 +54,18 @@ When it creates the sandbox org, Salesforce copies the metadata, and optionally
 
 Name of the sandbox org.
 
-# flags.name.description
-
-Name of the sandbox org.
-
 # flags.wait.summary
 
 Number of minutes to wait for the sandbox org to be ready.
 
-# flags.poll-interval.summary
-
-Number of seconds to wait between retries.
+# flags.wait.description
 
-# flags.async.summary
-
-Don't wait for the sandbox create to complete.
+If the command continues to run after the wait period, the CLI returns control of the terminal window to you and returns the job ID. To resume checking the sandbox creation, rerun this command.
 
 # flags.use-most-recent.summary
 
 Use the most recent sandbox create request.
 
-# flags.use-most-recent.description
-
-Use the most recent sandbox create request.
-
 # error.pollIntervalGreaterThanWait
 
 The poll interval (%d seconds) can't be larger that wait (%d in seconds).
@@ -86,11 +76,11 @@ No sandbox name or job ID were provided.
 
 # error.LatestSandboxRequestNotFound
 
-Please retry the command using either the --name or --job-id flags.
+Retry the command using either the --name or --job-id flags.
 
 #error.NoSandboxRequestFound
 
-Could not find a sandbox request using the provided sandbox name or job ID.
+Couldn't find a sandbox creation request using the provided sandbox name or job ID.
 
 # error.ResumeTimeout
 

src/commands/env/create/sandbox.ts

@@ -77,6 +77,7 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxProcessObje
     wait: Flags.duration({
       char: 'w',
       summary: messages.getMessage('flags.wait.summary'),
+      description: messages.getMessage('flags.wait.description'),
       min: 1,
       unit: 'minutes',
       defaultValue: 30,
@@ -94,6 +95,7 @@ export default class CreateSandbox extends SandboxCommandBase<SandboxProcessObje
     }),
     async: Flags.boolean({
       summary: messages.getMessage('flags.async.summary'),
+      description: messages.getMessage('flags.async.description'),
       exclusive: ['wait', 'poll-interval'],
     }),
     name: Flags.string({

src/commands/env/resume/sandbox.ts

@@ -43,6 +43,7 @@ export default class ResumeSandbox extends SandboxCommandBase<SandboxProcessObje
     wait: Flags.duration({
       char: 'w',
       summary: messages.getMessage('flags.wait.summary'),
+      description: messages.getMessage('flags.wait.description'),
       min: 0,
       unit: 'minutes',
       helpValue: '<minutes>',
@@ -51,7 +52,6 @@ export default class ResumeSandbox extends SandboxCommandBase<SandboxProcessObje
     name: Flags.string({
       char: 'n',
       summary: messages.getMessage('flags.name.summary'),
-      description: messages.getMessage('flags.name.description'),
       parse: (name: string): Promise<string> => {
         if (name.length > 10) {
           throw messages.createError('error.SandboxNameLength', [name]);
@@ -70,7 +70,6 @@ export default class ResumeSandbox extends SandboxCommandBase<SandboxProcessObje
     'use-most-recent': Flags.boolean({
       char: 'l',
       summary: messages.getMessage('flags.use-most-recent.summary'),
-      description: messages.getMessage('flags.use-most-recent.description'),
     }),
     'target-org': Flags.optionalOrg({
       char: 'o',