fix: clean up messages for two convert commands

Author: jshackell-sfdc

messages/convert.mdapi.md

@@ -1,64 +1,52 @@
 # summary
 
-convert metadata from the Metadata API format into the source format
+Convert metadata retrieved via Metadata API into the source format used in Salesforce DX projects.
 
 # description
 
-Converts metadata retrieved via Metadata API into the source format used in Salesforce DX projects.
+To use Salesforce CLI to work with components that you retrieved via Metadata API, first convert your files from the metadata format to the source format using this command.
 
-To use Salesforce CLI to work with components that you retrieved via Metadata API, first convert your files from the metadata format to the source format using "sfdx force:mdapi:convert".
-
-To convert files from the source format back to the metadata format, so that you can deploy them using "<%= config.bin %> project deploy", run "<%= config.bin %> project convert source".
+To convert files from the source format back to the metadata format, run "<%= config.bin %> project convert source".
 
 # examples
 
-- $ <%= config.bin %> <%= command.id %> -r path/to/metadata
-
-- $ <%= config.bin %> <%= command.id %> -r path/to/metadata -d path/to/outputdir
-
-# flags.root-dir
-
-the root directory containing the Metadata API–formatted metadata
-
-# flags.output-dir
-
-the output directory to store the source–formatted files
+- Convert metadata formatted files in the specified directory into source formatted files; writes converted files to your default package directory:
 
-# flags.manifest
+  $ <%= config.bin %> <%= command.id %> --root-dir path/to/metadata
 
-file path to manifest (package.xml) of metadata types to convert.
+- Similar to previous example, but writes converted files to the specified output directory:
 
-# flags.metadata-path
+  $ <%= config.bin %> <%= command.id %> --root-dir path/to/metadata --output-dir path/to/outputdir
 
-comma-separated list of metadata file paths to convert
+# flags.root-dir.summary
 
-# flags.metadata
+Root directory that contains the Metadata API–formatted metadata.
 
-comma-separated list of metadata component names to convert
+# flags.output-dir.summary
 
-# flagsLong.root-dir
+Directory to store your files in after they’re converted to source format; can be an absolute or relative path.
 
-The root directory that contains the metadata you retrieved using Metadata API.
+# flags.manifest.summary
 
-# flagsLong.output-dir
+File path to manifest (package.xml) of metadata types to convert.
 
-The directory to store your files in after they’re converted to the source format. Can be an absolute or relative path.
+# flags.metadata-path.summary
 
-# flagsLong.manifest
+Comma-separated list of paths to the local metadata files to convert.
 
-- The complete path to the manifest (package.xml) file that specifies the metadata types to convert.
+# flags.metadata.summary
 
-- If you specify this parameter, don’t specify --metadata or --source-path.
+Comma-separated list of metadata component names to convert.
 
-# flagsLong.metadata-path
+# flags.manifest.description
 
-- A comma-separated list of paths to the local metadata files to convert. The supplied paths can be to a single file (in which case the operation is applied to only one file) or to a folder (in which case the operation is applied to all metadata types in the directory and its sub-directories).
+If you specify this parameter, don’t specify --metadata or --source-path.
 
-- If you specify this parameter, don’t specify --manifest or --metadata. If the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes.
+# flags.metadata-path.description
 
-# flagsLong.metadata
+The supplied paths can be to a single file (in which case the operation is applied to only one file) or to a folder (in which case the operation is applied to all metadata types in the directory and its sub-directories).
 
-A comma-separated list of metadata component names to convert.
+If you specify this flag, don’t specify --manifest or --metadata. If the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes.
 
 # expectedDirectory
 

messages/convert.source.md

@@ -1,59 +1,58 @@
 # summary
 
-convert source into Metadata API format
+Convert source-formatted files into metadata that you can deploy using Metadata API.
 
 # description
 
-convert source into Metadata API format
-Converts source-formatted files into metadata that you can deploy using Metadata API.
-To convert source-formatted files into the metadata format, so that you can deploy them using Metadata API,
-run "<%= config.bin %> project convert mdapi". Then deploy the metadata using "<%= config.bin %> project deploy".
+To convert source-formatted files into the metadata format, so that you can deploy them using Metadata API, run this command. Then deploy the metadata using "<%= config.bin %> project deploy".
 
 To convert Metadata API–formatted files into the source format, run "<%= config.bin %> project convert mdapi".
 
 To specify a package name that includes spaces, enclose the name in single quotes.
 
 # examples
 
-- $ <%= config.bin %> <%= command.id %> -r path/to/source
+- Convert source-formatted files in the specified directory into metadata-formatted files; writes converted files into a new directory:
 
-- $ <%= config.bin %> <%= command.id %> -r path/to/source -d path/to/outputdir -n 'My Package'
+  $ <%= config.bin %> <%= command.id %> --root-dir path/to/source
 
-# flags.root-dir
+- Similar to previous example, but writes converted files to the specified output directory and associates the files with the specified package:
 
-a source directory other than the default package to convert
+  $ <%= config.bin %> <%= command.id %> --root-dir path/to/source --output-dir path/to/outputdir --package-name 'My Package'
 
-# flags.output-dir
+# flags.root-dir.summary
 
-output directory to store the Metadata API–formatted files in
+Source directory other than the default package to convert.
 
-# flags.package-name
+# flags.output-dir.summary
 
-name of the package to associate with the metadata-formatted files
+Output directory to store the Metadata API–formatted files in.
 
-# flags.manifest
+# flags.package-name.summary
 
-file path to manifest (package.xml) of metadata types to convert.
+Name of the package to associate with the metadata-formatted files.
 
-# flags.source-path
+# flags.manifest.summary
 
-comma-separated list of paths to the local source files to convert
+Path to the manifest (package.xml) file that specifies the metadata types to convert.
 
-# flags.metadata
+# flags.source-path.summary
 
-comma-separated list of metadata component names to convert
+Comma-separated list of paths to the local source files to convert.
 
-# flagsLong.manifest
+# flags.metadata.summary
 
-- The complete path to the manifest (package.xml) file that specifies the metadata types to convert.
+Comma-separated list of metadata component names to convert.
 
-- If you specify this parameter, don’t specify --metadata or --source-path.
+# flags.manifest.description
 
-# flagsLong.source-path
+If you specify this parameter, don’t specify --metadata or --source-path.
 
-- A comma-separated list of paths to the local source files to convert. The supplied paths can be to a single file (in which case the operation is applied to only one file) or to a folder (in which case the operation is applied to all metadata types in the directory and its sub-directories).
+# flags.source-path.description
 
-- If you specify this parameter, don’t specify --manifest or --metadata.
+The supplied paths can be to a single file (in which case the operation is applied to only one file) or to a folder (in which case the operation is applied to all metadata types in the directory and its sub-directories).
+
+If you specify this parameter, don’t specify --manifest or --metadata.
 
 # success
 

src/commands/project/convert/mdapi.ts

@@ -48,36 +48,33 @@ export class Mdapi extends SfCommand<ConvertMdapiJson> {
       aliases: ['rootdir'],
       deprecateAliases: true,
       char: 'r',
-      description: messages.getMessage('flagsLong.root-dir'),
-      summary: messages.getMessage('flags.root-dir'),
+      summary: messages.getMessage('flags.root-dir.summary'),
       required: true,
       exists: true,
     }),
     'output-dir': Flags.directory({
       aliases: ['outputdir'],
       deprecateAliases: true,
       char: 'd',
-      description: messages.getMessage('flagsLong.output-dir'),
-      summary: messages.getMessage('flags.output-dir'),
+      summary: messages.getMessage('flags.output-dir.summary'),
     }),
     manifest: Flags.file({
       char: 'x',
-      description: messages.getMessage('flagsLong.manifest'),
-      summary: messages.getMessage('flags.manifest'),
+      description: messages.getMessage('flags.manifest.description'),
+      summary: messages.getMessage('flags.manifest.summary'),
       exists: true,
     }),
     'metadata-path': arrayWithDeprecation({
       char: 'p',
       aliases: ['metadatapath'],
       deprecateAliases: true,
-      description: messages.getMessage('flagsLong.metadata-path'),
-      summary: messages.getMessage('flags.metadata-path'),
+      description: messages.getMessage('flags.metadata-path.description'),
+      summary: messages.getMessage('flags.metadata-path.summary'),
       exclusive: ['manifest', 'metadata'],
     }),
     metadata: arrayWithDeprecation({
       char: 'm',
-      description: messages.getMessage('flagsLong.metadata'),
-      summary: messages.getMessage('flags.metadata'),
+      summary: messages.getMessage('flags.metadata.summary'),
       exclusive: ['manifest', 'metadatapath'],
     }),
   };

src/commands/project/convert/source.ts

@@ -45,39 +45,39 @@ export class Source extends SfCommand<ConvertResultJson> {
       aliases: ['rootdir'],
       deprecateAliases: true,
       char: 'r',
-      summary: messages.getMessage('flags.root-dir'),
+      summary: messages.getMessage('flags.root-dir.summary'),
       exists: true,
     }),
     'output-dir': Flags.directory({
       aliases: ['outputdir'],
       deprecateAliases: true,
       default: `metadataPackage_${Date.now()}`,
       char: 'd',
-      summary: messages.getMessage('flags.output-dir'),
+      summary: messages.getMessage('flags.output-dir.summary'),
     }),
     'package-name': Flags.string({
       char: 'n',
       aliases: ['packagename'],
       deprecateAliases: true,
-      summary: messages.getMessage('flags.package-name'),
+      summary: messages.getMessage('flags.package-name.summary'),
     }),
     manifest: Flags.file({
       char: 'x',
-      description: messages.getMessage('flags.manifest'),
-      summary: messages.getMessage('flagsLong.manifest'),
+      summary: messages.getMessage('flags.manifest.summary'),
+      description: messages.getMessage('flags.manifest.description'),
       exists: true,
     }),
     'source-path': arrayWithDeprecation({
       char: 'p',
       aliases: ['sourcepath'],
       deprecateAliases: true,
-      description: messages.getMessage('flags.source-path'),
-      summary: messages.getMessage('flagsLong.source-path'),
+      description: messages.getMessage('flags.source-path.description'),
+      summary: messages.getMessage('flags.source-path.summary'),
       exclusive: ['manifest', 'metadata'],
     }),
     metadata: arrayWithDeprecation({
       char: 'm',
-      description: messages.getMessage('flags.metadata'),
+      summary: messages.getMessage('flags.metadata.summary'),
       exclusive: ['manifest', 'sourcepath'],
     }),
   };