fix: improve inline documentation (#172)

apps/cli/src/command/convert.command.ts

@@ -21,13 +21,14 @@ class BaseConvertCommand extends BaseCommand {
     super(name);
     this.option(
       '-f, --file <openapi-file-path>',
-      'OpenAPI configuration file path',
+      'OpenAPI specification file path',
     ).option('-o, --output <output-path>', 'output file path');
   }
 }
 
 const OpenAPICommand = new BaseConvertCommand('openapi')
-  .description('Converting OpenAPI to ADC Configuration')
+  .description('Convert an OpenAPI specification to equivalent ADC configuration.\n\nLearn more at: https://docs.api7.ai/enterprise/reference/openapi-adc')
+  .summary('convert OpenAPI spec to ADC configuration')
   .action(async () => {
     const opts = OpenAPICommand.optsWithGlobals<ConvertOptions>();
 
@@ -92,5 +93,6 @@ const OpenAPICommand = new BaseConvertCommand('openapi')
   });
 
 export const ConvertCommand = new BaseCommand('convert')
-  .description('Convert other API spec to ADC configurations')
+  .description('Convert API definitions in other formats to equivalent ADC configuration.')
+  .summary('convert API definitions in other formats to ADC configuration')
   .addCommand(OpenAPICommand);

apps/cli/src/command/diff.command.ts

@@ -158,14 +158,16 @@ export const DiffResourceTask = (
 
 export const DiffCommand = new BackendCommand<DiffOptions>(
   'diff',
-  'Show the difference between local and backend configurations',
+  'show differences between the local and the backend configurations',
+  'Compare the configuration in the specified file(s) with the backend configuration',
 )
   .option(
     '-f, --file <file-path>',
-    'The files you want to synchronize, can be set more than one.',
+    'file to compare',
     (filePath, files: Array<string> = []) => files.concat(filePath),
   )
   .addOption(NoLintOption)
+  .addExample('adc diff -f adc.yaml')
   .addExample('adc diff -f service-a.yaml -f service-b.yaml')
   .handle(async (opts) => {
     const backend = loadBackend(opts.backend, opts);

apps/cli/src/command/dump.command.ts

@@ -66,15 +66,16 @@ export const LoadRemoteConfigurationTask = ({
 
 export const DumpCommand = new BackendCommand<DumpOptions>(
   'dump',
-  'Dump configurations from the backend',
+  'save the configuration of the backend to a file',
+  'Save the configuration of the backend to the specified YAML file.',
 )
   .option(
     '-o, --output <file-path>',
-    'Specify the file path where data is dumped from the backend',
+    'path of the file to save the configuration',
     'adc.yaml',
   )
   .addExample('adc dump')
-  .addExample('adc dump -o other-name.yaml')
+  .addExample('adc dump -o service-configuration.yaml')
   .handle(async (opts) => {
     const backend = loadBackend(opts.backend, opts);
     const tasks = new Listr<TaskContext, typeof SignaleRenderer>(

apps/cli/src/command/helper.ts

@@ -10,16 +10,17 @@ import qs from 'qs';
 export class BaseCommand extends Command {
   private exmaples: Array<string> = [];
 
-  constructor(name: string, description?: string) {
+  constructor(name: string, summary?: string, description?: string) {
     super(name);
 
+    if (summary) this.summary(summary);
     if (description) this.description(description);
 
     // Add global flag - verbose
     this.addOption(
       new Option(
         '--verbose <integer>',
-        'Override verbose logging levels, it supports 0: no logs, 1: basic logs, 2: debug logs',
+        'set the verbosity level for logs (0: no logs, 1: basic logs, 2: debug logs)',
       )
         .argParser((val) => {
           const int = parseInt(val);
@@ -34,7 +35,7 @@ export class BaseCommand extends Command {
   public addExample(exmaple: string) {
     if (this.exmaples.length === 0)
       this.addHelpText('after', () => {
-        return `\nExample:\n\n${this.exmaples
+        return `\nExamples:\n\n${this.exmaples
           .map((example) => `  $ ${example}`)
           .join('\n')}\n`;
       });
@@ -45,8 +46,8 @@ export class BaseCommand extends Command {
 }
 
 export class BackendCommand<OPTS extends object = object> extends BaseCommand {
-  constructor(name: string, description?: string) {
-    super(name, description);
+  constructor(name: string, summary?: string, description?: string) {
+    super(name, summary, description);
 
     this.addBackendOptions();
   }
@@ -92,44 +93,44 @@ export class BackendCommand<OPTS extends object = object> extends BaseCommand {
     };
 
     this.addOption(
-      new Option('--backend <backend>', 'Type of backend to connect')
+      new Option('--backend <backend>', 'type of backend to connect to')
         .env('ADC_BACKEND')
         .choices(['apisix', 'api7ee'])
         .default('apisix'),
     )
       .addOption(
         new Option(
           '--server <string>',
-          'HTTP address of backend. This value can also be set using the environment variable ADC_SERVER environment variable',
+          'HTTP address of the backend',
         )
           .env('ADC_SERVER')
           .default('http://localhost:9180'),
       )
       .addOption(
-        new Option('--token <string>', 'Token used to access the backend').env(
+        new Option('--token <string>', 'token for ADC to connect to the backend').env(
           'ADC_TOKEN',
         ),
       )
       .addOption(
         new Option(
           '--gateway-group <string>',
-          'Gateway group used to specify the gateway group to operate [API7EE backend only]',
+          'gateway group to operate on (only supported for "api7ee" backend)',
         )
           .env('ADC_GATEWAY_GROUP')
           .default('default'),
       )
       .addOption(
         new Option(
-          '--label-selector <selectors>',
-          'Filter for resource labels (e.g., labelKey=labelValue)',
+          '--label-selector <labelKey=labelValue>',
+          'filter resources by labels',
         ).argParser((val, previous: Record<string, string> = {}) =>
           Object.assign(previous, qs.parse(val, { delimiter: ',' })),
         ),
       )
       .addOption(
         new Option(
           '--include-resource-type <string>',
-          'Filter for resource types, contains only the specified type',
+          'filter resources that only contains the specified type',
         )
           .conflicts('excludeResourceType')
           .choices(Object.values(ADCSDK.ResourceType))
@@ -138,7 +139,7 @@ export class BackendCommand<OPTS extends object = object> extends BaseCommand {
       .addOption(
         new Option(
           '--exclude-resource-type <string>',
-          'Filter for resource types, not contains only the specified type',
+          'filter resources that does not contain the specified type',
         )
           .conflicts('includeResourceType')
           .choices(Object.values(ADCSDK.ResourceType))
@@ -147,7 +148,7 @@ export class BackendCommand<OPTS extends object = object> extends BaseCommand {
       .addOption(
         new Option(
           '--timeout <duration>',
-          'Set a request timeout for the client to connect with Backend Admin API (in duration, e.g., 10s, 1h10m)',
+          'timeout for adc to connect with the backend (examples: 10s, 1h10m)',
         )
           .default(10000, '10s')
           .argParser((value) => {
@@ -157,7 +158,7 @@ export class BackendCommand<OPTS extends object = object> extends BaseCommand {
       .addOption(
         new Option(
           '--ca-cert-file <string>',
-          'Path to CA certificate for verifying the Backend Admin API',
+          'path to the CA certificate to verify the backend',
         )
           .env('ADC_CA_CERT_FILE')
           .argParser((value) =>
@@ -170,38 +171,38 @@ export class BackendCommand<OPTS extends object = object> extends BaseCommand {
       .addOption(
         new Option(
           '--tls-client-cert-file <string>',
-          'Path to Mutual TLS client certificate for verifying the Backend Admin API',
+          'path to the mutual TLS client certificate to verify the backend',
         )
           .env('ADC_TLS_CLIENT_CERT_FILE')
           .argParser((value) =>
             processCertificateFile(
               value,
-              'The specified Mutual TLS client certificate file does not exist',
+              'The specified mutual TLS client certificate file does not exist',
             ),
           ),
       )
       .addOption(
         new Option(
           '--tls-client-key-file <string>',
-          'Path to Mutual TLS client key for verifying the Backend Admin API',
+          'path to the mutual TLS client key to verify the backend',
         )
           .env('ADC_TLS_CLIENT_KEY_FILE')
           .argParser((value) =>
             processCertificateFile(
               value,
-              'The specified Mutual TLS client key file does not exist',
+              'The specified mutual TLS client key file does not exist',
             ),
           ),
       )
       .addOption(
         new Option(
           '--tls-skip-verify',
-          `Disable verification of Backend Admin API TLS certificate`,
+          `disable the verification of the backend TLS certificate`,
         )
           .env('ADC_TLS_SKIP_VERIFY')
           .default(false),
       );
   }
 }
 
-export const NoLintOption = new Option('--no-lint', 'Disable lint check');
+export const NoLintOption = new Option('--no-lint', 'disable lint check');

apps/cli/src/command/index.ts

@@ -14,9 +14,10 @@ export const setupCommands = (): Command => {
   const program = new Command('adc');
 
   program
+    .description('API Declarative CLI (ADC) is a utility to manage API7 Enterprise and Apache APISIX declaratively.\n\nLearn more at: https://docs.api7.ai/enterprise/reference/adc')
     .configureHelp({ showGlobalOptions: true })
     .passThroughOptions()
-    .version('0.12.1');
+    .version('0.12.1', '-v, --version', 'display ADC version');
 
   program
     .addCommand(PingCommand)

apps/cli/src/command/lint.command.ts

@@ -57,13 +57,15 @@ export const LintTask = (): ListrTask<{ local: ADCSDK.Configuration }> => ({
 
 export const LintCommand = new BaseCommand('lint')
   .description(
-    'Check provided configuration files, local execution only, ensuring inputs meet ADC requirements',
+    'Lint the local configuration file(s) to ensure it meets ADC requirements.',
   )
+  .summary('lint the local configuration')
   .option(
-    '-f, --file <file-path...>',
-    'The files you want to synchronize, can be set more than one.',
+    '-f, --file <file-path>',
+    'file to lint',
     (filePath, files: Array<string> = []) => files.concat(filePath),
   )
+  .addExample('adc lint -f adc.yaml')
   .addExample('adc lint -f service-a.yaml -f service-b.yaml')
   .action(async () => {
     const opts = LintCommand.optsWithGlobals();

apps/cli/src/command/ping.command.ts

@@ -8,15 +8,16 @@ type PingOptions = BackendOptions;
 
 export const PingCommand = new BackendCommand<PingOptions>(
   'ping',
-  'Verify connectivity with backend',
+  'check connectivity with the backend',
+  'Check connectivity with the configured backend.',
 ).handle(async (opts) => {
   const backend = loadBackend(opts.backend, opts);
 
   try {
     await backend.ping();
-    console.log(chalk.green('Connected to backend successfully!'));
+    console.log(chalk.green(`Connected to the "${opts.backend}" backend successfully!`));
   } catch (err) {
-    console.log(chalk.red(`Unable to connect to the backend, ${err}`));
+    console.log(chalk.red(`Unable to connect to the "${opts.backend}" backend. ${err}`));
     process.exit(1);
   }
 });

apps/cli/src/command/sync.command.ts

@@ -19,14 +19,16 @@ type SyncOption = BackendOptions & {
 
 export const SyncCommand = new BackendCommand<SyncOption>(
   'sync',
-  'Sync local configurations to backend',
+  'sync the local configuration to the backend',
+  'Synchronize the configuration from the local file(s) to the backend.',
 )
   .option(
     '-f, --file <file-path>',
-    'The files you want to synchronize, can be set more than one.',
+    'file to synchronize',
     (filePath, files: Array<string> = []) => files.concat(filePath),
   )
   .addOption(NoLintOption)
+  .addExample('adc sync -f adc.yaml')
   .addExample('adc sync -f service-a.yaml -f service-b.yaml')
   .handle(async (opts) => {
     const backend = loadBackend(opts.backend, opts);

libs/backend-api7/src/index.ts

@@ -172,7 +172,7 @@ export class BackendAPI7 implements ADCSDK.Backend {
 
         const gatewayGroups = resp?.data?.list;
         if (!gatewayGroups.length) {
-          throw Error(`Gateway group ${this.gatewayGroup} does not exist`);
+          throw Error(`Gateway group "${this.gatewayGroup}" does not exist`);
         }
         ctx.gatewayGroupId = this.gatewayGroupId = gatewayGroups[0].id;
       },