Very large set of details in terminal suggestions for Where-object

[mjbvz]

Testing #241771

1. Trigger terminal suggestions for where-object in powershell

Bug
There's a overwhelming list of variations:

[Tyriar]

This also happens in the pwsh extension as it's the help provided for that:

Closing as out of scope for us, but FYI @andyleejordan in case you have not considered this experience.

[andyleejordan]

That's indeed all the available variations of that cmdlet, and how its help is currently written in PowerShell: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/where-object?view=powershell-7.5

@sdwheeler looks like in https://github.com/PowerShell/PowerShell/blob/f467823d5d1495c30cd1e29c5bb2975f429cb9bd/src/System.Management.Automation/engine/InternalCommands.cs#L1280C20-L1280C67 the help included is literally generated from that help document...can we improve it?

[sdwheeler]

@andyleejordan Nothing to fix here. Where-Object has 32 parameter sets (the maximum allowed). That's the way it's designed.

[andyleejordan]

@sdwheeler but could the documentation be written more like:

Where-Object
     [-InputObject <PSObject>]
     [-Property] <String>
     [[-Value] <Object>]
     -Match | -CEQ | -NE ...
     [<CommonParameters>]

for all the parameter sets where only one parameter is varying. This is how most man pages are written when other values are shared.

[sdwheeler]

@andyleejordan Short answer is NO. That's not how the tools work and that's not how PowerShell works. Each parameter set is a unique thing with a unique name. With the new version of PlatyPS that Jim created, your proposed format would not work.

[Tyriar]

@sdwheeler fwiw as someone not very deep in the pwsh ecosystem I agree with the OP that this is pretty overwhelming. Plus it means that when we add detailed help underneath it would almost certainly be scrolled off screen unless we limit these up to 32 entries by say only showing the first 3 and truncating with an ellipsis. Alternatively, we could maybe do the consolidation on our end if we notice the output of Get-Command is repetitious.

This is an early version of what intellisense looks like for a zsh builtin that we pull from the man page:

[sdwheeler]

We can't change how the help is written. There are too many details and dependencies to explain here.

The problem isn't just that a command can have 32 parameter sets. We also have commands that have LOTS of parameters. Invoke-RestMethod has 4 parameter sets with 54-56 parameters each. How should that be rendered by IntelliSense?

[Tyriar]

@sdwheeler makes sense, thanks. I'm thinking we'll just heavily truncate them when looking at the command, as that information will eventually be surfaced in intellisense for the args and parameter hints if we choose to do that in the terminal.

[sdwheeler]

I think it would be useful to wrap the text in the IntelliSense window so that you can see the full syntax of a parameter set.

[Tyriar]

@sdwheeler I agree 👍, we'll probably try align that part with how TypeScript presents it:

[andyleejordan]

@Tyriar let me know how you end up truncating and displaying it and we can do the same over in the extension.