Repository navigation
Get-Help / -? should show the parameter-set name above each syntax diagram #6856
Description
Related: #4135, #4715, #4626, #4137
Especially with complex commands that have several parameter sets, the parameter-set names are important to quickly understand the context of a given syntax diagram.
The help-topic sources seems to already contain the information, but it shows neither with Get-Help / -? nor online - see MicrosoftDocs/PowerShell-Docs#2422
A simple example:
Steps to reproduce
Get-Content -?Expected behavior
...
SYNTAX
Path (Default)
Get-Content [-Encoding {Unknown | String | Unicode | Byte | BigEndianUnicode | UTF8 | UTF7 | UTF32 | Ascii | Default | Oem | BigEndianUTF32}] [-Delimiter <String>] [-Force] [-Raw] [-Wait] [-Stream <String>] [-UseTransaction] [-Credential
<PSCredential>] [-Exclude <String[]>] [-Filter <String>] [-Include <String[]>] -LiteralPath <String[]> [-ReadCount <Int64>] [-TotalCount <Int64>] [-Tail <Int32>] [<CommonParameters>]
LiteralPath
Get-Content [-Path] <String[]> [-Encoding {Unknown | String | Unicode | Byte | BigEndianUnicode | UTF8 | UTF7 | UTF32 | Ascii | Default | Oem | BigEndianUTF32}] [-Delimiter <String>] [-Force] [-Raw] [-Wait] [-Stream <String>] [-UseTransaction]
[-Credential <PSCredential>] [-Exclude <String[]>] [-Filter <String>] [-Include <String[]>] [-ReadCount <Int64>] [-TotalCount <Int64>] [-Tail <Int32>] [<CommonParameters>]
...
Actual behavior
...
SYNTAX
Get-Content [-Encoding {Unknown | String | Unicode | Byte | BigEndianUnicode | UTF8 | UTF7 | UTF32 | Ascii | Default | Oem | BigEndianUTF32}] [-Delimiter <String>] [-Force] [-Raw] [-Wait] [-Stream <String>] [-UseTransaction] [-Credential
<PSCredential>] [-Exclude <String[]>] [-Filter <String>] [-Include <String[]>] -LiteralPath <String[]> [-ReadCount <Int64>] [-TotalCount <Int64>] [-Tail <Int32>] [<CommonParameters>]
Get-Content [-Path] <String[]> [-Encoding {Unknown | String | Unicode | Byte | BigEndianUnicode | UTF8 | UTF7 | UTF32 | Ascii | Default | Oem | BigEndianUTF32}] [-Delimiter <String>] [-Force] [-Raw] [-Wait] [-Stream <String>] [-UseTransaction]
[-Credential <PSCredential>] [-Exclude <String[]>] [-Filter <String>] [-Include <String[]>] [-ReadCount <Int64>] [-TotalCount <Int64>] [-Tail <Int32>] [<CommonParameters>]
...
Environment data
Written as of:
PowerShell Core v6.0.2
Activity
BrucePay commentedon May 11, 2018
FYI: parameter set names are not considered to be user-facing data and there is no expectation that they should be sensible to the end-user. They're only intended to be used by the command developer and changing a parameter set name is not considered to be a breaking change.
In practice, they're mostly some amalgam of the distinguishing parameter names, sometimes with "Set" on the end so it might be useful information in some (maybe most) cases. But, as proposed, it also takes up a lot of space. It might be more effective to show the syntax with the distinguishing parameters first instead of displaying them all alphabetically.
mklement0 commentedon May 11, 2018
Bruce Payette (@BrucePay):
That would certainly help. Ultimately it is about being able to quickly discern what's unique about a parameter set.
Understood, but for the purpose of quickly informing users (as opposed to programmatic processing) that in itself is not a problem.
If chosen carefully - and I understand that that is not a current requirement - a parameter-set name can potentially communicate more than the just the name of the unique parameter.
True, but a condensed display doesn't help if it hinders readability.
This is a bit of a tangent, but:
I find the current syntax diagrams hard to parse visually in general and lacking in important information (see also the linked issues).
Consider the more "spacious" but far more legible representation Keith Hill (@rkeithhill) mentions in #4135 (comment).
fowl2 commentedon Jul 16, 2019
FWIW, they are actually displayed by the ISE - each tab is a parameter set:
microsoft-github-policy-service commentedon Nov 16, 2023
This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.
microsoft-github-policy-service commentedon Nov 16, 2023
This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.
microsoft-github-policy-service commentedon Nov 23, 2023
This issue has been marked as "No Activity" as there has been no activity for 6 months. It has been closed for housekeeping purposes.