fix: show hidden options in help

[laggingreflex]

Options with description: false will now show up help

fixes #851

[Morishiri]

Ternary operator which is nested 3 times is really hard to understand. I think it will be better if it will be splitted in some more cases to be easier to read.

[bcoe]

Looks good to me, do you sign off too @Morishiri?

[laggingreflex]

Having second thoughts on this. Currently it shows options if their description is set to false. (as per your comment @bcoe). Would it be better if it shows options when description is left blank, and doesn't show when it's set to false? This would also be more inline with the current docs (as pointed out by @gajus)

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

Or would that break existing usage?

[gajus]

Would it be better if it shows options when description is left blank, and doesn't show when it's set to false? This would also be more inline with the current docs (as pointed out by @gajus)

👍

[bcoe]

@laggingreflex good catch; I'm with both you and @gajus on this.

Let's show the option if an empty string is provided for the description, hide on null, false, undefined.

Sound reasonable?

[gajus]

I still think that an explicit option should be used to make a parameter hidden. All this convention based behaviour is tricky to document/ remember.

As long as option is provided, it should be visible, unless that option contains configuration {hidden: true}, i.e.

.options({
  foo: {
    describe: 'FOO'
  },
  bar: {},
  baz: {
    describe: 'BAZ',
    hidden: true
  }
});

With this configuration,

• foo and bar are visible by default
• baz is visible if --yargs-show-hidden (or whatever) option is provided

The benefits of this approach:

• You can validate that describe value is a string
• Hidden options can have a description

[bcoe]

@gajus this argument seems reasonable to me, and I think we're inching up on a new major release of yargs any ways, with some of the work I've been doing around command parsing/number coercion.

@laggingreflex thoughts on the options discussed above?

[bcoe]

@laggingreflex this looks good to me; any idea why test coverage dropped so much?

[laggingreflex]

I was testing with .only locally which dropped the coverage. Fixed now.

Also this doesn't yet implement --yargs-show-hidden, I'm working on an alternative for that.

[bcoe]

@laggingreflex 👍 I'm working on a pretty big 10.x release, it would be nice to land this in it (I'd also love help testing the changes on master when you have time).

[laggingreflex]

Instead of --yargs-show-hidden (@gajus) how about this:

yargs.showHelp('log', {showHidden: [true|false]})

This gives the user more control. Like maybe they wouldn't want to show hidden commands at all. Or maybe they'd want it behind a custom flag. This way they can implement it themselves.

It however require that the user implements the --help themselves too:

const argv = yargs
  .options({
    baz: {
      describe: 'BAZ',
      hidden: true
    },
    'show-hidden': {
      describe: 'Show hidden options',
      type: 'boolean'
    },
  })
  .help(false)
  .argv

if (yargs.help) {
  yargs.showHelp('log', {hidden: argv.showHidden})
}

[bcoe]

@laggingreflex I'd be tempted to discuss --yargs-show-hidden in a separate issue. I think that this feature is enough of an edge-case that there's benefit to landing this feature first... mainly, I'm on the fence about --yargs-show-hidden; for starters I don't like baking the yargs name into a flag, so I'd probably call it something like --show-hidden (folks calling this flag feels like an edge-case to me though).

[laggingreflex]

I've undone the last commit and I'll move it to a separate issue/pr.

This now only enables the {hidden: true} option to hide the option from --help (instead of by omitting the description).