get-help: Improve presentation of aliased parameters

[wisemoth]

trafficstars

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.

[kilasuit]

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

I agree however that's the ideal world and not the current real world. Whilst I'd also like us to get to the ideal world, I was being realistic in my adding of the resolution labels, but not closing the issue, because for now currently that is the right resolution to the issue raised, I did so, as to keep a historical trial of things that we have a resolution to, even if it isn't ideal. But I am also glad that this issue was also reviewed by @SeeminglyScience because he's right that this is an enhancement to the interactive help system - I was just providing additional clarity for others that may read this issue in future & was also why I didn't close this issue as I do think we can improve things.

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.

I don't see us being unable to get there, however it isn't going to be an easy journey based on my experience of how things currently are. Some thoughts though is that the help text should be improved as such that it comes as closely from the command definition as possible, which is why comment based help tends to be the best for this. This isn't going to be an easy fix, but I am sure that it can be done.

[SeeminglyScience]

Some better tooling around parameter discovery in general would be nice. I have something in my profile that gives me this output:

Though for something like Invoke-Command, that does output quite a few pages of info.

[theJasonHelmick]

@wisemoth - Thank you for reporting this issue with Aliases. We have been working on a fix to the display of the help files and documentation to better highlight the presentation of Aliases. Im adding @sdwheeler as he is also a part of this. No timeline yet to discuss, but actively being worked on.

[microsoft-github-policy-service[bot]]

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[bot]]

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[bot]]

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[bot]]

This issue has been marked as "No Activity" as there has been no activity for 6 months. It has been closed for housekeeping purposes.