Add --help-hidden for use with _hiddenFromHelp

[keith]

Swift Package Manager adopted _hiddenFromHelp, the resulting help is
much more approachable for basic usage, but leaves no way to view
all the advanced options it accepts. This takes from swiftc's + clang's
playbook and adds a hidden --help-hidden flag that prints all help,
including those using _hiddenFromHelp

Related: https://bugs.swift.org/browse/SR-15224

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[keith]

@natecook1000 can you review?

[rauhul]

I think we wanted to explore a more general notion of help "levels", I'm not 100% sure how @natecook1000 wanted to approach this.

I was thinking that we could add a HelpLevel type and allow @Option/etc... to take a HelpLevel as a parameter. SAP would find all the HelpLevels in the program and create flags at runtime, ex:

extension HelpLevel {
  static let experimental = HelpLevel(/*custom string if desired*/)
  static let unixCompatibility = HelpLevel()
}

@Option(..., helpLevel: .experimental)
var foo: Int
@Option(..., helpLevel: .unixCompatibility)
var bar: String

// --help (default, provided by sap)
// --help-experimental
// --help-unix-compatibility
// --help-all/everything (provided by sap, created if any levels are used)

[keith]

Interesting, yea it sounds like in that case we'd want to remove the current underscored attribute and replace it with one of those.

[natecook1000]

@keith Sorry to leave this open for so long — @rauhul is right, I've grand designs in my head that I thought were described in a couple of open issues, but don't seem to be. I'll fix that problem next.

[keith]

Any suggestions in the meantime to fix this for adopters of that feature? I can't blame swiftpm for not wanting to expose all the underlying options by default, but the end result is there's no way to see them without reading source code

[rauhul]

Maybe --experimental-help-hidden to indicate this is not a stable interface?

[keith]

Updated to that for discussion

[natecook1000]

Thanks for your patience on this, @keith!

Coming back to it, and I think we could just add this directly, without the experimental- prefix. I've opened an issue describing another level of visibility for arguments that should be excluded from this extended help screen as #384. The 'titled option groups' feature is described in #267 — if this PR is landed before that is implemented, then that feature could include things like --help-compiler-opts to get help about a specific hidden option group.

A few additional questions:

1. Does this extended help screen also show arguments/flags/options that have help: .hidden or shouldDisplay: false set?
2. How does this flag interact with custom help flags? e.g. if the command has specified an alternate set of help flag names in its command configuration, should this piggy-back off those, or just stay as --help-hidden?
3. Should we be detecting whether there are hidden arguments to display, and including a note (like "Pass --help-hidden to view more options") in the default help screen? What is the behavior if --help-hidden is called when there's no hidden help?

[weissi]

didn't see this PR. So I filed #403 :)

[keith]

I love the idea of --help-compiler-opts, that would be perfect for SwiftPM's case.

Does this extended help screen also show arguments/flags/options that have help: .hidden or shouldDisplay: false set?

I think there's a core question here of: should users of this library be able to entirely hide flags from their users? In the current implementation here they cannot. I haven't poked around enough other argument parser to know how common it is to need this. In general as a user of these things I don't like flags being hidden, and would prefer their docs disclaim that they should be "considered private" if necessary, but maybe that's not the right balance. If the custom groups behavior was implemented maybe that would be enough to have a custom group that was never shown to allow this.

How does this flag interact with custom help flags? e.g. if the command has specified an alternate set of help flag names in its command configuration, should this piggy-back off those, or just stay as --help-hidden?

Ah yep, sounds like if we go this route it should mirror those, which might be weird if someone was doing something significantly different with the flag, but would probably still be better than having the static one.

Should we be detecting whether there are hidden arguments to display, and including a note (like "Pass --help-hidden to view more options") in the default help screen? What is the behavior if --help-hidden is called when there's no hidden help?

Yes great point, we should. Maybe we don't enable this flag at all if there aren't any as well?

[natecook1000]

Thanks so much for your work on this, @keith! ❤️ We're going to merge the changes here and iterate a bit before the next release.

[natecook1000]

@swift-ci Please test

[weissi]

🎉 thank you all!

[keith]

Sounds good! Thanks everyone