Documentation for Option.HelpName inaccurate and mysterious

[elgonzo]

command-line-api/src/System.CommandLine/Option.cs

Lines 38 to 49 in 28ad8f7

	/// <summary>
	/// Gets or sets the name of the Option when displayed in help.
	/// </summary>
	/// <value>
	/// The name of the option when displayed in help.
	/// </value>
	/// <remarks>Useful for localization, as it's not used for actual parsing.</remarks>
	public string? HelpName
	{
	get => Argument.HelpName;
	set => Argument.HelpName = value;
	}

The documentation comments for Option.HelpName inaccurately state that it sets the name for the option for the help. That is not true, as it sets the (placeholder) name for the option argument; it doesn't alter the option name in the help.

Also, it features a mysterious remark "Useful for localization". How?

I'd like to submit a PR for this, rephrasing "name of the Option" to "name of the Option argument".

However, what about this "Useful for localization" remark? Is that a leftover from the older code base and can i remove this? Or is this something that will be addressed and become clear with the eventual proper release? Because as it currently stands, it's rather unclear what this remark is supposed to mean.

[KalleOlaviNiemitalo]

The "Useful for localization" remark might be related to my comments #1891 (comment) and #2046 (comment), as justification for why both Name and HelpName should exist; but in that case, I'd expect it to be on Argument.HelpName rather than Option.HelpName.

[elgonzo]

Argument.HelpName does not have this localization remark:

command-line-api/src/System.CommandLine/Argument.cs

Lines 43 to 46 in 28ad8f7

	/// <summary>
	/// The name used in help output to describe the argument.
	/// </summary>
	public string? HelpName { get; set; }

I also don't like the property name Option.HelpName, it's too fuzzy considering that the option has a name (passed to the ctor) displayed in the help as well as the option argument also having a name in the help. If it were not a breaking change, Option.ArgumentHelpName would have been a better property name. Not sure if making Option.Argument public and obsoleting Option.HelpName would make sense, either, because then you would have still a duplication of APIs where you can configure other stuff through an Option property (like Option.Arity) and an Option.Argument property (like Option.Argument.Arity), which is also not really neat unless you also obsolete all those Option properties that proxy Option.Argument properties -- which is also rather disruptive in my opinion.

[jonsequitur]

If it were not a breaking change, Option.ArgumentHelpName would have been a better property name.

This is probably a reasonable breaking change.

[elgonzo]

Should i go forward with the PR, also refactoring Option.HelpName to Option.ArgumentHelpName, or do you first need to discuss this internally?

If you give me green light for the PR, should i leave the somewhat vague "Useful for localization" remark as-is?