test: update return structure and improve tests descriptions

Author: miguelmarcondesf

doc/api/util.md

@@ -2055,11 +2055,11 @@ changes:
 * Returns: {Object} The parsed command line arguments:
   * `values` {Object} A mapping of parsed option names with their {string}
     or {boolean} values.
+    * `help` {string | undefined} Formatted help text for all options provided. Only included if general `help` text
+      is available.
   * `positionals` {string\[]} Positional arguments.
   * `tokens` {Object\[] | undefined} See [parseArgs tokens](#parseargs-tokens)
     section. Only returned if `config` includes `tokens: true`.
-  * `printUsage` {string | undefined} Formatted help text for all options provided. Only included if general `help` text
-    is available.
 
 Provides a higher level API for command-line argument parsing than interacting
 with `process.argv` directly. Takes a specification for the expected arguments
@@ -2109,7 +2109,7 @@ console.log(values, positionals);
 
 `parseArgs` supports automatic formatted help text generation for command-line options. To use this feature, provide
 general help text using the `help` config property, and also
-add a `help` property to each option can be optionally included.
+a `help` property to each option can be optionally included.
 
 ```mjs
 import { parseArgs } from 'node:util';

lib/internal/util/parse_args/parse_args.js

@@ -328,9 +328,8 @@ function formatHelpTextForPrint(longOption, optionConfig) {
   helpTextForPrint += `--${longOption}`;
   if (type === 'string') {
     helpTextForPrint += ' <arg>';
-  } else if (type === 'boolean') {
-    helpTextForPrint += '';
   }
+
   if (help) {
     if (helpTextForPrint.length > layoutSpacing) {
       helpTextForPrint += '\n' + ''.padEnd(layoutSpacing) + help;
@@ -462,7 +461,7 @@ const parseArgs = (config = kEmptyObject) => {
   });
 
   if (help && printUsage.length > 0) {
-    result.printUsage = printUsage;
+    result.values.help = printUsage;
   }
 
   return result;

test/parallel/test-parse-args.mjs

@@ -1082,58 +1082,66 @@ test('help value for option must be a string', () => {
   );
 });
 
+test('when option has help text values but help arg value is not provided, then no help value appear', () => {
+  const args = ['-f', 'bar'];
+  const options = { foo: { type: 'string', short: 'f', help: 'help text'} };
+  const expected = { values: { __proto__: null, foo: 'bar' }, positionals: []};
+  const result = parseArgs({ args, options, allowPositionals: true });
+  assert.deepStrictEqual(result, expected);
+})
+
 test('when option has short and long flags, then both appear in usage', () => {
   const args = ['-f', 'bar'];
   const options = { foo: { type: 'string', short: 'f', help: 'help text' } };
   const help = 'Description for some awesome stuff:';
   const printUsage = help + '\n-f, --foo <arg>               help text';
-  const expected = { values: { __proto__: null, foo: 'bar' }, positionals: [], printUsage };
+  const expected = { values: { __proto__: null, foo: 'bar', help: printUsage }, positionals: [] };
   const result = parseArgs({ args, options, allowPositionals: true, help });
   assert.deepStrictEqual(result, expected);
 });
 
-test('when help arg with help value for short group option is added, then add help text', () => {
+test('when options has short group flags, then both appear in usage', () => {
   const args = ['-fm', 'bar'];
   const options = { foo: { type: 'boolean', short: 'f', help: 'help text' },
                     moo: { type: 'string', short: 'm', help: 'help text' } };
   const help = 'Description for some awesome stuff:';
   const printUsage = help + '\n-f, --foo                     help text\n-m, --moo <arg>               help text';
-  const expected = { values: { __proto__: null, foo: true, moo: 'bar' }, positionals: [], printUsage };
+  const expected = { values: { help: printUsage, __proto__: null, foo: true, moo: 'bar' }, positionals: [] };
   const result = parseArgs({ args, options, allowPositionals: true, help });
   assert.deepStrictEqual(result, expected);
 });
 
-test('when help arg with help value for short option and value is added, then add help text', () => {
+test('when options has short flag with value, then both appear in usage', () => {
   const args = ['-fFILE'];
   const options = { foo: { type: 'string', short: 'f', help: 'help text' } };
   const help = 'Description for some awesome stuff:';
   const printUsage = help + '\n-f, --foo <arg>               help text';
-  const expected = { values: { __proto__: null, foo: 'FILE' }, positionals: [], printUsage };
+  const expected = { values: { help: printUsage, __proto__: null, foo: 'FILE' }, positionals: [] };
   const result = parseArgs({ args, options, allowPositionals: true, help });
   assert.deepStrictEqual(result, expected);
 });
 
-test('when help arg with help value for lone long option is added, then add help text', () => {
+test('when options has long flag, then it appear in usage', () => {
   const args = ['--foo', 'bar'];
   const options = { foo: { type: 'string', help: 'help text' } };
   const help = 'Description for some awesome stuff:';
   const printUsage = help + '\n--foo <arg>                   help text';
-  const expected = { values: { __proto__: null, foo: 'bar' }, positionals: [], printUsage };
+  const expected = { values: { help: printUsage, __proto__: null, foo: 'bar' }, positionals: [] };
   const result = parseArgs({ args, options, allowPositionals: true, help });
   assert.deepStrictEqual(result, expected);
 });
 
-test('when help arg with help value for lone long option and value is added, then add help text', () => {
+test('when options has long flag with value, then both appear in usage', () => {
   const args = ['--foo=bar'];
   const options = { foo: { type: 'string', help: 'help text' } };
   const help = 'Description for some awesome stuff:';
   const printUsage = help + '\n--foo <arg>                   help text';
-  const expected = { values: { __proto__: null, foo: 'bar' }, positionals: [], printUsage };
+  const expected = { values: { help: printUsage, __proto__: null, foo: 'bar' }, positionals: [] };
   const result = parseArgs({ args, options, allowPositionals: true, help });
   assert.deepStrictEqual(result, expected);
 });
 
-test('when help arg with help values and without explicit help texts, then add help text', () => {
+test('when options has help values with and without explicit texts, then all appear in usage', () => {
   const args = [
     '-h', '-a', 'val1',
   ];
@@ -1174,10 +1182,10 @@ test('when help arg with help values and without explicit help texts, then add h
   '-L, --looooooooooooooongHelpText <arg>\n' +
   '                              Very long option help text for demonstration purposes';
 
-  assert.strictEqual(result.printUsage, printUsage);
+  assert.strictEqual(result.values.help, printUsage);
 });
 
-test('when help arg but no help text is available, then add help text', () => {
+test('when general help text and options with no help values, then all appear in usage', () => {
   const args = ['-a', 'val1', '--help'];
   const help = 'Description for some awesome stuff:';
   const options = { alpha: { type: 'string', short: 'a' }, help: { type: 'boolean' } };
@@ -1188,5 +1196,5 @@ test('when help arg but no help text is available, then add help text', () => {
 
   const result = parseArgs({ args, options, help });
 
-  assert.strictEqual(result.printUsage, printUsage);
+  assert.strictEqual(result.values.help, printUsage);
 });