How to Get Help Right For PSTypeNames

GetHelpRightForPSTypeNames.ps1

#
# How to get help right for an array of PSTypeNames
#

# Awesome function to get some random stuff
# The important thing is that we get objects with an added PSTypeName of 'Stuff'

Function Get-Stuff {
    [cmdletbinding()]
    param(
        [ValidateRange(0,4)]
        [int[]]$StuffID
    )
    process {
        $Stuff = @(
            [pscustomobject]@{PSTypeName='Stuff';StuffID=0;Measurement=(Get-Random)}
            [pscustomobject]@{PSTypeName='Stuff';StuffID=1;Measurement=(Get-Random)}
            [pscustomobject]@{PSTypeName='Stuff';StuffID=2;Measurement=(Get-Random)}
            [pscustomobject]@{PSTypeName='Stuff';StuffID=3;Measurement=(Get-Random)}
            [pscustomobject]@{PSTypeName='Stuff';StuffID=4;Measurement=(Get-Random)}
        )
        if($PSBoundParameters.ContainsKey('StuffID')) {
            $Stuff | Where-Object StuffID -in $StuffID
        } else {
            $Stuff
        }
    }
}

# So lets get some objects

$stuff = Get-Stuff -StuffID 1,3
$stuff

# $Stuff returns the following:
<# 

StuffID Measurement
------- -----------
      1  1536015795
      3  1958061410
#>

# Now let's add a function which can consume an array of objects with PSTypeName = 'Stuff'

function Add-StuffUgly {
    [cmdletbinding()]
    param(
        [parameter(Mandatory)]
        [string]$Identity,

        [parameter(Mandatory)]
        [PSTypeName('Stuff')]
        $Stuff
    )
    process {
        "Adding {0} Stuff to {1}" -f $Stuff.count,$Identity 
    }
}

Add-StuffUgly -Identity 'Something' -Stuff $stuff 

<# 

Adding 2 Stuff to Something

#>

# Here is the issue though, in the syntax and in the help we see -Stuff taking a singlular object, not an array of 'Stuff' objects. Which is missleading
# Clearly the [PSTypeName('Stuff')] attributes allows for arrays to be passed in, since we get a count of 2 objects. 
# What we want to see is -Stuff taking the type <Stuff[]> in the Syntax and Help text.

Get-Command Add-StuffUgly -Syntax 

<# 

Add-StuffUgly [-Identity] <string> [-Stuff] <Stuff> [<CommonParameters>]

#>

Get-help Add-StuffUgly -Parameter Stuff

<# 

-Stuff <Stuff>
    
    Required?                    true
    Position?                    1
    Accept pipeline input?       false
    Parameter set name           (All)
    Aliases                      None
    Dynamic?                     false
#>  

# What we want to see is the type <Stuff[]> in the help.

# So how do we fix this? Well multiple PSTypeName attributes can be added to a parameter. 
# So we add another PSTypeName saying 'Stuff[]'. 
#
# This does not indicate an array of Stuff to PowerShell, rather that -Stuff takes two different type of PSTypeName objects, where one just happens to have brackets in the name, Stuff[].

function Add-Stuff {
    [cmdletbinding()]
    param(
        [parameter(Mandatory)]
        [string]$Identity,

        [parameter(Mandatory)]
        [PSTypeName('Stuff')]
        [PSTypeName('Stuff[]')]
        $Stuff
    )
    process {
        "Adding {0} Stuff to {1}" -f $Stuff.count,$Identity 
    }
}

Add-Stuff -Identity 'Something' -Stuff $stuff 

<# 

Adding 2 Stuff to Something

#>


Get-Command Add-Stuff -Syntax 

<# 

Add-Stuff [-Identity] <string> [-Stuff] <Stuff[]> [<CommonParameters>]

#>

Get-help Add-Stuff -Parameter Stuff

<#

-Stuff <Stuff[]>
    
    Required?                    true
    Position?                    1
    Accept pipeline input?       false
    Parameter set name           (All)
    Aliases                      None
    Dynamic?                     false
    
#>

# Now we can finally sleep care free. :)