fix: update messages

messages/audit.messages.md

@@ -2,39 +2,35 @@
 
 Audit messages in a plugin's messages directory to locate unused messages and missing messages that have references in source code.
 
-# description
-
-Audit messages in a plugin's messages directory to locate unused messages and missing messages that have references in source code.
-
 # examples
 
-sf dev audit messages
-sf dev audit messages --json
-sf dev audit messages --messages-dir ./messages --source-dir ./src
+- Audit messages using default directories:
 
-# flags.project-dir.summary
+  <%= config.bin %> <%= command.id %>
+
+- Audit messages in the "messages" directory in the current working directory; the plugin's source directory is in "src":
 
-Location project where messages are to be audited.
+  <%= config.bin %> <%= command.id %> --messages-dir ./messages --source-dir ./src
 
-# flags.project-dir.description
+# flags.project-dir.summary
 
-The project directory.
+Location of the project where messages are to be audited.
 
 # flags.messages-dir.summary
 
-Location of the message bundle directory.
+Directory that contains the plugin's message files. 
 
 # flags.messages-dir.description
 
-The directory that holds the message bundle files. The default is the messages directory in the current working directory.
+The default is the "messages" directory in the current working directory.
 
 # flags.source-dir.summary
 
-Location of the plugin's source code.
+Directory that contains the plugin's source code.
 
 # flags.source-dir.description
 
-The directory that holds the plugin's source code. The default is the src directory in the current working directory.
+The default is the "src" directory in the current working directory.
 
 # noUnusedMessagesFound
 

messages/configure.repo.md

@@ -1,23 +1,25 @@
 # summary
 
-Configure github repo for Actions pipeline.
+Configure a GitHub repo for the GitHub Actions pipeline.
 
 # description
 
-Sets up labels and exempts the CLI bot for branch protection and PR rules
+Sets up labels and exempts the CLI bot for branch protection and PR rules.
 
 # flags.repository.summary
 
-The github owner/repo
+GitHub owner/repo for which you want to configure GitHub Actions.
 
 # flags.dryRun.summary
 
-Make no changes
+Make no changes.
 
 # examples
 
-- <%= config.bin %> <%= command.id %> -r salesforcecli/testPackageRelease
+- Configure the repo "tesetPackageRelease", with owner "salesforcecli", for GitHub Actions.
+
+  <%= config.bin %> <%= command.id %> --repository salesforcecli/testPackageRelease
 
 # flags.bot.summary
 
-The github login/username for the bot.
+GitHub login/username for the bot.

messages/configure.secrets.md

@@ -1,21 +1,23 @@
 # summary
 
-Ensures a repo has correct access to secrets based on its workflows
+Ensures a GitHub repo has correct access to secrets based on its workflows.
 
 # description
 
 Inspects a repo's yaml files and verifies that secrets required are available for the repo (either set at the repo level or shared via organization-level secrets).
 
-This command requires scope:admin permissions to inspect the org secrets and admin access to the repo to inspect the repo secrets
+This command requires scope:admin permissions to inspect the org secrets and admin access to the repo to inspect the repo secrets.
 
 # flags.repository.summary
 
-The github owner/repo
+Github owner/repo.
 
 # flags.dryRun.summary
 
-Make no changes
+Make no changes.
 
 # examples
 
-- <%= config.bin %> <%= command.id %> -r salesforcecli/testPackageRelease
+- Ensure secrets access for the repo "tesetPackageRelease", with owner "salesforcecli":
+
+- <%= config.bin %> <%= command.id %> --repository salesforcecli/testPackageRelease

messages/dev.convert.messages.md

@@ -1,24 +1,25 @@
 # summary
 
-Convert a .json messages file
+Convert a .json messages file into Markdown.
 
 # description
 
-Converts a .json messages file to markdown. Preserves the filename and the original messages file, creating a new file with the markdown extensions. Once you review the file, delete it
+Preserves the filename and the original messages file, then creates a new file with the Markdown extension and standard headers for the command and flag summaries, descriptions, and so on. After you review the new Markdown file, delete the old .json file.
 
 # flags.filename.summary
 
-Filename to convert
+Filename to convert.
 
 # flags.project-dir.summary
 
-Location of the project whose messages are to be audited.
+Location of the project whose messages are to be converted.
 
-# flags.project-dir.description
+# examples
 
-Location of the project whose messages are to be audited.
+- Convert the my-command.json message file into my-command.md with the standard messages headers:
 
-# examples
+  <%= config.bin %> <%= command.id %> --filename my-command.json
+
+- Similar to previous example, but specify the plugin project directory:
 
-- <%= config.bin %> <%= command.id %> --filename something.json
-- <%= config.bin %> <%= command.id %> --project-dir ./path/to/plugin --filename something.json
+- <%= config.bin %> <%= command.id %> --project-dir ./path/to/plugin --filename my-command.json

package.json

@@ -106,10 +106,16 @@
         "description": "Commands for sf plugin development.",
         "subtopics": {
           "convert": {
-            "description": "description for dev.convert"
+            "description": "Commands to help you convert an sfdx plugin to sf."
           },
           "generate": {
             "description": "Commands for generating sf plugins, commands, and hooks."
+          },
+          "audit": {
+            "description": "Commands for auditing a plugin."
+          },
+          "configure": {
+            "description": "Commands for configuring repos and secrets."
           }
         }
       }

src/commands/dev/audit/messages.ts

@@ -52,13 +52,11 @@ type Node = FileNode | BundleNode | MessageNode | MessageRefNode | BundleRefNode
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.load('@salesforce/plugin-dev', 'audit.messages', [
   'summary',
-  'description',
   'examples',
   'duplicateBundles',
   'flags.messages-dir.summary',
   'flags.messages-dir.description',
   'flags.project-dir.summary',
-  'flags.project-dir.description',
   'flags.source-dir.summary',
   'flags.source-dir.description',
   'missingBundlesFound',
@@ -75,14 +73,12 @@ const messages = Messages.load('@salesforce/plugin-dev', 'audit.messages', [
 
 export default class AuditMessages extends SfCommand<AuditResults> {
   public static readonly summary = messages.getMessage('summary');
-  public static readonly description = messages.getMessage('description');
   public static readonly examples = messages.getMessages('examples');
 
   public static readonly flags = {
     'project-dir': Flags.directory({
       summary: messages.getMessage('flags.project-dir.summary'),
       char: 'p',
-      description: messages.getMessage('flags.project-dir.description'),
       default: '.',
       aliases: ['projectdir'],
     }),

src/commands/dev/convert/messages.ts

@@ -18,7 +18,6 @@ const messages = Messages.load('@salesforce/plugin-dev', 'dev.convert.messages',
   'examples',
   'flags.filename.summary',
   'flags.project-dir.summary',
-  'flags.project-dir.description',
 ]);
 
 export type DevConvertMessagesResult = {
@@ -37,7 +36,6 @@ export default class DevConvertMessages extends SfCommand<DevConvertMessagesResu
     'project-dir': Flags.directory({
       summary: messages.getMessage('flags.project-dir.summary'),
       char: 'p',
-      description: messages.getMessage('flags.project-dir.description'),
       default: '.',
       aliases: ['projectdir'],
     }),