Powershell 5.1: alias descriptions are missing in my module

I have a module PhriInfrastructure which codifies our DevOps procedures at my organization. It has a function Test-IsLocalhost that I've aliased to Get-IsLocalhost for backwards-compatibility reasons.

I've tried to apply a description to the alias, like so:

New-Alias -Name Get-IsLocalhost -Value Test-IsLocalhost -Description "Get-IsLocalhost was renamed Test-IsLocalhost to better-match Powershell verb standards"

however, when I try to pull metadata about the alias in the command-line

Import-Module .\PowerShellModules\src\PhriInfrastructure -Force
(Get-Alias Get-IsLocalhost) | Format-List -Property *
Get-Help Get-IsLocalhost

the Description field is empty in both the Get-Help and the Get-Alias (the underlying Test-IsLocalhost command only has a #.Synopsis.

Meanwhile, if I attempt to create the alias direct from command-line, it appears in the alias members (but still not in the get-help).

Is there a way to expose the alias description properly? Or some better way to say "don't use this alias, use the primary one?" Is this just a bug in how Powershell 5.1 exports aliases in modules?

Solution

Indeed, whatever -Description value you specify seems to be lost when an alias is exported from a module (observed in Windows PowerShell and in PowerShell (Core) up to a least v7.3.6, current as of this writing).

Is this just a bug in how PowerShell 5.1 exports aliases in modules?

I'd say yes, and I encourage you to create a bug report in the GitHub repo.

if I attempt to create the alias direct from command-line, it appears in the alias members (but still not in get-help).

By design, aliases don't have their own help - Get-Help simply resolves an alias to its target command and shows its help, so you'll never get information about the alias itself that way.

some better way to say "don't use this alias, use the primary one?"

Generally, the .Description property of alias definitions is rarely used (it isn't set for any of the built in aliases), which is also suggested by the fact that it doesn't even surface in Get-Alias's for-display output unless you explicitly ask for it (e.g., via Format-List *)
You could implement Get-IsLocalhost as a function that delegates to Test-IsLocalHost, which allows you to provide its own comment-based help, which could be as simple as:
```
function Get-IsLocalHost {
<#
.SYNOPSIS
Get-IsLocalhost was renamed Test-IsLocalhost to better-match PowerShell verb standards.
#>
  Test-IsLocalHost @args
}
```
- If you prefer a runtime warning, you can use the System.ObsoleteAttribute attribute as follows; note that the comment-based help is used to automatically forward to Test-IsLocalHost's help here:
```
function Get-IsLocalHost {
<#
.ForwardHelpTargetName Test-IsLocalHost
.ForwardHelpCategory Function
#>
  [Obsolete("Get-IsLocalhost was renamed Test-IsLocalhost to better-match PowerShell verb standards.")]
  param()
  Test-IsLocalHost @args
}
```
- On invocation, a warning is unconditionally emitted via the Warning output stream, which can be silenced with 3>$null (if you wanted to also support -WarningAction SilentlyContinue, you'd have to make the function an advanced one, which would require duplicating the target function's parameter declarations, and invoking it with Test-IsLocalHost @PSBoundParameters.)