PowerShell Tip - Adding Help in the PARAM statement

2014/01/26 | 1 minute read |

It’s always a good idea to include help within your functions ! You never know who might benefit from it.

With PowerShell adding help to your script, function and module is a really easy thing to do.

Help in the PARAM statements

A very cool way to add some help to your script parameters is to add comments within the PARAM statement block. With this method you do not need to write a .PARAMETERdirective for each paremeters. However you are required to write at least one directive in the Comment Based Help block (.SYNOPSISor .DESCRIPTION) to be able to use it.

Example:

<#
    .SYNOPSIS
        This function will get some cool stuff
#>
    PARAM(
        # Specifies the computer name
        $ComputerName,
    
        # Specifies the Log directory Path
        $Logs = C:\lazywinadmin\logs
    )#PARAM

Then use Get-Help against your function/script

Get-Help Get-Something -Parameter *

This command will only return the Parameters information with the help we added in the PARAM statement

-ComputerName <string>
    Specifies the ComputerName

    Required?                    true
    Position?                    named
    Default value
    Accept pipeline input?       false
    Accept wildcard characters?  false


-Logs <string>
    Specifies the Log directory Path

    Required?                    false
    Position?                    named
    Default value                c:\lazywinadmin\logs
    Accept pipeline input?       false
    Accept wildcard characters?  false

</string></string>

Even if this tip is pretty cool, I would still recommend to use the Comment Based Help block to have a centralized place to put all the help !