Merge pull request #1866 from Automattic/update/docs-pt-dev-env-options

Updating command option descriptions to follow the VIP-CLI style guide

src/bin/vip-config-software-update.js

@@ -54,7 +54,7 @@ const cmd = command( {
 	wildcardCommand: true,
 	usage,
 } ).examples( examples );
-cmd.option( 'yes', 'Auto-confirm update' );
+cmd.option( 'yes', 'Skip the confirmation prompt and automatically submit "y".' );
 cmd.argv( process.argv, async ( arg, opt ) => {
 	const { app, env } = opt;
 	const { softwareSettings } = env;

src/bin/vip-dev-env-create.js

@@ -71,7 +71,7 @@ const cmd = command( {
 		undefined,
 		processSlug
 	)
-	.option( 'title', 'A descriptive value for the WordPress Site Title. Default is "VIP Dev").' )
+	.option( 'title', 'A descriptive value for the WordPress Site Title. Default is "VIP Dev".' )
 	.option(
 		'multisite',
 		'Create environment as a multisite. Accepts "y" for a subdomain multisite, "subdirectory" (recommended) for a subdirectory multisite, or "false". Default is "y".',

src/bin/vip-sync.js

@@ -92,10 +92,10 @@ command( {
 
 	if ( syncing ) {
 		if ( environment.syncProgress.status === 'running' ) {
-			console.log( chalk.yellow( 'Note:' ), 'A data sync is already running' );
+			console.log( chalk.yellow( 'Note:' ), 'A data sync is already running.' );
 		} else {
-			console.log( chalk.yellow( 'Note:' ), 'Someone recently ran a data sync on this site' );
-			console.log( chalk.yellow( 'Note:' ), 'Please wait a few minutes before trying again' );
+			console.log( chalk.yellow( 'Note:' ), 'Someone recently ran a data sync on this site.' );
+			console.log( chalk.yellow( 'Note:' ), 'Please wait a few minutes before trying again.' );
 		}
 	}
 
@@ -183,7 +183,7 @@ command( {
 					error: 'API returned `failed` status',
 				} );
 
-				out.push( `${ marks.failed } Data Sync is finished for ${ opts.app.name }` );
+				out.push( `${ marks.failed } Data Sync is finished for ${ opts.app.name }.` );
 				out.push( '' );
 				break;
 
@@ -193,7 +193,7 @@ command( {
 
 				await trackEvent( 'sync_command_success' );
 
-				out.push( `${ marks.success } Data Sync is finished for ${ opts.app.name }` );
+				out.push( `${ marks.success } Data Sync is finished for ${ opts.app.name }.` );
 				out.push( '' );
 				break;
 		}

src/lib/cli/command.js

@@ -470,7 +470,7 @@ args.argv = async function ( argv, cb ) {
 					Boolean( options.exportFileErrorsToJson ) &&
 					! [ 'false', 'no' ].includes( options.exportFileErrorsToJson );
 				info.push( {
-					key: 'Export any file errors encountered to a JSON file instead of a plain text file',
+					key: 'Export any file errors encountered to a JSON file instead of a plain text file.',
 					value: options.exportFileErrorsToJson ? '✅ Yes' : `${ chalk.red( 'x' ) } No`,
 				} );
 				break;
@@ -566,25 +566,41 @@ export default function ( opts ) {
 	};
 
 	if ( _opts.appContext || _opts.requireConfirm ) {
-		args.option( 'app', 'Specify the app' );
+		args.option(
+			'app',
+			'Target an application. Accepts a string value for the application name or an integer for the application ID.'
+		);
 	}
 
 	if ( _opts.envContext || _opts.childEnvContext ) {
-		args.option( 'env', 'Specify the environment' );
+		args.option( 'env', 'Target an environment. Accepts a string value for the environment type.' );
 	}
 
 	if ( _opts.requireConfirm ) {
-		args.option( 'force', 'Skip confirmation', false );
+		args.option( 'force', 'Skip confirmation.', false );
 	}
 
 	if ( _opts.format ) {
-		args.option( 'format', 'Format results', 'table' );
+		args.option(
+			'format',
+			'Render output in a particular format. Accepts "table" (default), "csv", and "json".',
+			'table'
+		);
 	}
 
 	// Add help and version to all subcommands
-	args.option( 'help', 'Output the help for the (sub)command' );
-	args.option( 'version', 'Output the version number' );
-	args.option( 'debug', 'Activate debug output' );
+	args.option(
+		'help',
+		'Retrieve a description, examples, and available options for a (sub)command.'
+	);
+	args.option(
+		'version',
+		'Retrieve the version number of VIP-CLI currently installed on the local machine.'
+	);
+	args.option(
+		'debug',
+		'Generate verbose output during command execution to help identify or fix errors or bugs.'
+	);
 
 	return args;
 }

src/lib/dev-environment/dev-environment-cli.ts

@@ -858,48 +858,68 @@ export function processVersionOption( value: unknown ): string {
 	return value?.toString() ?? '';
 }
 
+const phpVersionsSupported: string = Object.keys( DEV_ENVIRONMENT_PHP_VERSIONS ).join( ', ' );
+
 export function addDevEnvConfigurationOptions( command: Args ): Args {
 	// We leave the third parameter to undefined on some because the defaults are handled in preProcessInstanceData()
 	return command
-		.option( 'wordpress', 'Use a specific WordPress version', undefined, processVersionOption )
-		.option( [ 'u', 'mu-plugins' ], 'Use a specific mu-plugins changeset or local directory' )
+		.option(
+			'wordpress',
+			'Manage the version of WordPress. Accepts a string value for major versions (6.x). Defaults to the most recent version of WordPress.',
+			undefined,
+			processVersionOption
+		)
+		.option(
+			[ 'u', 'mu-plugins' ],
+			'Manage the source for VIP MU plugins. Accepts "demo" (default) for a read-only image of the staging branch, or a path to a built copy of VIP MU plugins on the local machine.'
+		)
 		.option(
 			'app-code',
-			'Use the application code from a local directory or use "demo" for VIP skeleton code'
+			'Manage the source for application code. Accepts "demo" (default) for a read-only image of WordPress VIP skeleton application code, or a path to a VIP formatted application repo on the local machine.'
 		)
 		.option(
 			'phpmyadmin',
-			'Enable PHPMyAdmin component. By default it is disabled',
+			'Enable or disable phpMyAdmin, disabled by default. Accepts "y" (default value) to enable or "n" to disable. When enabled, refer to the value of "PHPMYADMIN URLS" in the information output for a local environment for the URL to access phpMyAdmin.',
+			undefined,
+			processBooleanOption
+		)
+		.option(
+			'xdebug',
+			'Enable or disable XDebug, disabled by default. Accepts "y" (default value) to enable or "n" to disable.',
 			undefined,
 			processBooleanOption
 		)
-		.option( 'xdebug', 'Enable XDebug. By default it is disabled', undefined, processBooleanOption )
 		.option(
 			'xdebug_config',
-			'Extra configuration to pass to xdebug via XDEBUG_CONFIG environment variable'
+			'Override some default configuration settings for Xdebug. Accepts a string value that is assigned to the XDEBUG_CONFIG environment variable.'
 		)
 		.option(
 			'elasticsearch',
-			'Enable Elasticsearch (needed by Enterprise Search)',
+			'Enable or disable Elasticsearch (required by Enterprise Search), disabled by default. Accepts "y" (default value) to enable or "n" to disable.',
 			undefined,
 			processBooleanOption
 		)
 		.option(
 			[ 'r', 'media-redirect-domain' ],
-			'Domain to redirect for missing media files. This can be used to still have images without the need to import them locally.',
+			'Configure media files to be proxied from a VIP Platform environment. Accepts a string value for the primary domain of the VIP Platform environment or "n" to disable the media proxy.',
 			undefined,
 			processMediaRedirectDomainOption
 		)
-		.option( 'php', 'Explicitly choose PHP version to use', undefined, processVersionOption )
+		.option(
+			'php',
+			`Manage the version of PHP. Accepts a string value for minor versions: ${ phpVersionsSupported }`,
+			undefined,
+			processVersionOption
+		)
 		.option(
 			[ 'A', 'mailpit' ],
-			'Enable Mailpit. By default it is disabled',
+			'Enable or disable Mailpit, disabled by default. Accepts "y" (default value) to enable or "n" to disable.',
 			undefined,
 			processBooleanOption
 		)
 		.option(
 			[ 'H', 'photon' ],
-			'Enable Photon. By default it is disabled',
+			'Enable or disable Photon, disabled by default. Accepts "y" (default value) to enable or "n" to disable.',
 			undefined,
 			processBooleanOption
 		);