get-help: Improve presentation of aliased parameters

[wisemoth]

Summary of the new feature / enhancement

aliased parameters are hard to discover in get-help. I recently raised what I thought was a documentation issue, only to see that in fact the documentation was present, but that the presentation of it was confusing.

Proposed technical implementation details (optional)

When attempting to discover Parameters all should be provided (certainly in -Detailed form), and so in the "documentation issue" I raised concerning the help for Invoke-Command I would think something like this would be useful in get-help output:

...
-Disconnected : alias, see InDisconnectedSession
...

In other words allow the alias to be a first-class parameter for the purposes of enumerating the parameters, but add a cross-link to the "other" parameter for the actual documentation.

[237dmitry]

I agree with the issue, aliases are hard to distinguish in help topics. For myself, I wrote a simple function to find out the parameter aliases:

function Find-ParametersAliases
{
    param (

        [Parameter(Mandatory)]
        [string]
        $command
    )

    foreach ($k in ($param = (Get-Command $command).Parameters).Keys) {

        [pscustomobject] @{
            Parameter = $param.$k.Name
            Aliases = $param.$k.Aliases -join ', '
        }
    }
}

[kilasuit]

@wisemoth Get-Help will, when the cmdlet help is complete (which only happens in an ideal world), show you aliases on individual parameters like so

Get-Help Get-ChildItem -Parameter Recurse

However as @237dmitry mentions above you actually can get this information when the help isn't complete by using Get-Command
This is one of the reasons why we've tried in the community to teach people to make use of the "holy trio" of Cmdlets for working out what you can do in PowerShell, Get-Help, Get-Command & Get-Member
Also as we don't have everything in an ideal world, the above techniques are the best way that we have.

You are best using the above function although I'd call it Find-ParameterAlias like so

function Find-ParameterAlias {
    [cmdletbinding()] # Not technically needed when a parameter is defined with [Parameter()] 
    [Alias('fpa')] # Added to be lazy and technically complete
    param (
        [Parameter(Mandatory)]
        [Alias('c')] # Technically not required but useful to know of & to be complete
        [string] 
        $command
    )
    $cmd = Get-Command $command 
    if ($cmd.CommandType -match 'Cmdlet|Function') {
        foreach ($k in ($param = $cmd.Parameters).Keys) {
            [pscustomobject] @{
                Parameter = $param.$k.Name
                Aliases = $param.$k.Aliases -join ', '
            }
        }
    } else {
            Write-Warning "Command $cmd is not a PowerShell Function or Cmdlet - Please refer to its own help/man pages"
    }
}

so then you can be even lazier and just run fpa gcm for get-command as an example
or if I run fpa Find-ParameterAlias it'll now show this

Hope this helps and as mentioned that due to not all cmdlets/functions having complete help this is currently as designed and I can't see this being something that can or ever will be able to be changed

[237dmitry]

[Alias('fpa')]

I set the same alias in $profile )) This alias is obvious.

[kilasuit]

@237dmitry - personally I think that it's better to set it in the function definition rather than outside of it as it automatically creates the alias though totally up to you how you manage your aliases for cmdlets/functions

[237dmitry]

personally I think that it's better to set it in the function definition rather than outside of it

I agree, this function used to be a script.

[wisemoth]

We shouldn't need to write functions to better understand command help/parameters.

In this case I saw -Disconnect for invoke-command mentioned in an article, so I wanted to find out more. It seems I have to either "reverse search" or direct my help inquiry to the level of a parameter, rather than the command, to:

a) learn that -Disconnect is an alias
b) find the "source" parameter for the alias.

My intention with this ticket is to seek presentational improvement in the output of get-help (and perhaps get-command -syntax and others) to improve the experience.