Allow marking options with "deprecated" help or visibility

[grynspan]

Let's say my CLI tool has an old option that's no longer valid:

@Option
public var sendToCzechslovakia = false

Since Czechoslovakia doesn't exist anymore, I've replace it with sendToEuropeanUnion, and I want to inform folks still using it to change their command-line incantations. Wouldn't it be nice if I could write:

@Option(help: .deprecated("Use --send-to-european-union instead"))
public var sendToCzechslovakia = false

And have it automatically be hidden and emit some sort of diagnostic message to stderr?

⚠️ --send-to-czechoslovakia is deprecated: use --send-to-european-union instead

[natecook1000]

This sounds handy, but I don't think there's enough of a consensus around how to display those kinds of messages to implement it as a library feature. You can implement that yourself by:

• providing both flags
• using validate() to print a message if sendToCzechslovakia is true
• using a computed property to make is easy to access sendToEuropeanUnion || sendToCzechslovakia within your command

[rauhul]

how to display those kinds of messages

Seems like we might need a hook for users to decide how to emit the messages. ideally it would be a build time configuration

[grynspan]

I can implement it myself, sure. :)

Was suggesting having a baked-in feature with a (semi-)canonical output might be nice.

[bkhouri]

I agree this would be beneficial. One option could be to emit a deprecated to the console when the deprecated option is used.

[heckj]

Since I've been working on a semi-related bit of this - if we were to generate documentation (markdown/docc) for an executable using this tool, what would you prefer to see for options like this? A deprecation callout (maybe like API deprecation, encouraging a specific alternative)? Hidden from the CLI docs? Or just leave it in and don't mark anything?

[grynspan]

A deprecation callout would make sense to me.

[rgoldberg]

I think that emitting documentation for deprecated constructs should be cascading configurable for all types of documentation (command-like help, man pages, Markdown, etc.).

Configuration should be cascading in code for commands, option groups, args, flags & options; via argument when generating documentation; via argument when calling command-line help.

You should be able to apply one visibility for all outputs of different visibilities for different outputs.

One documentation visibility value should defer to the value of the existing visibility property.

I'll defer to others about whether the default should be emit or omit for different constructs, different outputs, etc.

[grynspan]

I don't have strong feelings about those details—I do want something in this space so we can improve the overall experience using our CLI tools though.