options without description to not appear in --help

[gajus]

yargs@7.0.2

#!/usr/bin/env node

// @flow

import yargs from 'yargs';
import passthroughService from './commands/passthroughService';

yargs
  .command(passthroughService)
  .option('logstash', {
    describe: 'Logstash host:port'
  })
  .help()
  .parse(process.argv.slice(1));

// ./commands/passthroughService;

export default {
  builder: (yargs: Object) => {
    return yargs
      .options({
        forward: {
          type: 'string'
        },
        listen: {
          default: 'http://0.0.0.0:3000',
          type: 'string'
        }
      });
// [..]

$ babel-node src/bin/forwardProxy.js passthrough-service --help
Options:
  --logstash  Logstash host:port
  --help      Show help                                                [boolean]
  --listen                             [string] [default: "http://0.0.0.0:3000"]

Note the missing forward option.

[nexdrew]

@gajus Yes, you're quite correct, but I believe this is intentional (or, at least, was at some point in the past). As you can see here, options are only included in help content if they (1) have a description, (2) are required, or (3) have a default value. I'm not sure when this rationale was determined or exactly why it is this way - I mean it kinda makes sense - but I believe yargs has been this way for as long as I've used it, which goes back to at least an early version of 3.x.

Would you like to propose a change? Should yargs include all options in help content by default? Does it even make sense to have "hidden" or "undocumented" options?

In the meantime, a quick workaround is to give each option a description.

[gajus]

Does it even make sense to have "hidden" or "undocumented" options?

@bcoe What is the logic behind this?

[bcoe]

@gajus I believe the idea was that it would look ugly to have an argument with no description; and also it gives a way to provide hidden options;

I'd be inclined to revisit this decision; if you've explicitly created an option, I think we should show it; one question though, should we warn if no description is provided?

[gajus]

should we warn if no description is provided?

No. Whats the reason you think it should?

Good parameter names is like good variable naming. If you name it well, you don't need a description, e.g. --database-password. If you name your param --dba then it is your own fault, adding a description should not be a solution for this. If the requirement is brevity, encourage good naming and promote use of aliases. It is perfectly fine to have --database-password parameter with -P alias.

This wouldn't even be a breaking change. The docs say:

exports.describe: string used as the description for the command in help text, use false for a hidden command

Fine. If describe is set to false (boolean), make it private (although, I'd rather see this as a separate boolean option private which would allow to have description and visibility of the args could be controlled using ENV variable or some other mechanism).

[DiegoZoracKy]

I was just trying to make it work when i stumbled upon something that can solve this case, but, i think that it shouldn't have been solved in this way.

if instead of .option(), we set a .describe() (without any .option() at all), the option will then be shown on --help and also will be parsed as an option. Is this intentional?

let args = yargs.usage('$0 <cmd> [args]')
.describe(`weird`)
.help()
.argv;

// Try --help
// Then try --weird and see it parsed as an option
console.log('args', args);

[bcoe]

@DiegoZoracKy @gajus I like the idea of requiring that folks explicitly set describe to false to show an option with no description.

would happily accept a patch.

[brewster1134]

to hide from the help menu, you can pass false for the description

.command('foo', false, ...)