Heisenberg was here: Aliases for PowerShell parameters only appear in cmdlet help when you do NOT document the cmdlet

Question

In the process of trying to make the documentation for my PowerShell cmdlets (written in C#, not scripted) as complete as possible, I made an interesting discovery. If I include a proper MAML help file (e.g. MyModule.dll-Help.xml) then displaying help for a cmdlet's parameter that has one or more aliases might look like this:

PS> Get-Help Set-MySetting -param ItemType
-ItemType <ItemTypeChoice>
    The type for the item.    
    Required?                    false
    Position?                    4
    Default value                String
    Accept pipeline input?       true (ByPropertyName)
    Accept wildcard characters?  false

If, on the other hand, I remove that help file and reload my module, help for the same parameter--now just reflected from the code itself by Get-Help--might look like this:

PS> Get-Help Set-MySetting -param ItemType
-ItemType <ItemTypeChoice>
    The type for the item.    
    Required?                    false
    Position?                    4
    Accept pipeline input?       true (ByPropertyName)
    Parameter set name           (All)
    Aliases                      Type, SettingType
    Dynamic?                     false

Note the presence of the Aliases property in the second instance and its absence in the first.

Of course, one first thinks that my MAML must be incorrect. That possibility is even more likely given the fact that through extensive web searching I have yet to find anything remotely like a definitive source for the MAML XML schema(!). However, if my MAML is incorrect, then so is the MAML used for PowerShell's own core cmdlets, because that is where I copied it from, considering it to be a reliable source (C:\Windows\System32\WindowsPowerShell\v1.0\en-US\Microsoft.PowerShell.Commands.Management.dll-help.xml).

But the key evidence of a problem is that, even though some of the PowerShell core cmdlets in that file have aliases, they also do not report the aliases when you invoke Get-Help! Here's an example:

PS> Get-Help Add-Computer -param DomainName
-DomainName <String>
    Specifies the domain to which the computers are added. This parameter is required when adding the computers to a domain.    
    Required?                    true
    Position?                    1
    Default value                
    Accept pipeline input?       false
    Accept wildcard characters?  false

Here's the start of the MAML Definition for the DomainName parameter of Add-Computer--note the aliases defined at the end:

<command:parameter required="true" variableLength="false"
    globbing="false" pipelineInput="false" position="1" aliases="DN,Domain">

Thus, Get-Help knows how to report on aliases when it has to do the work itself via reflection, but it fails to report on aliases when provided in the aliases attribute of <command:parameter>.

The Question

What is the true problem?

1. Get-Help is expecting aliases to be somewhere other than the aliases attribute of <command:parameter>.
2. Get-Help is failing to look for aliases in the MAML at all when given a MAML file.

If (1), and someone can identify the correct way to specify aliases, then there's an easy workaround for my own cmdlets. If (2)... time to file an issue on Connect!

Answer 1

I had the same issue, and have been able to work around it by adding the Aliases into the parameter <maml:description> section.