PowerShell Tip - Adding Help in the PARAM statement

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 .PARAMETER directive for each paremeters. However you are required to write at least one directive in the Comment Based Help block (.SYNOPSIS or .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 
    Specifies the ComputerName

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


-Logs 
    Specifies the Log directory Path

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

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 !


Thanks for reading! If you have any questions, leave a comment or send me an email at fxcat@lazywinadmin.com. I invite you to follow me on Twitter @lazywinadm / Google+ / LinkedIn. You can also follow the LazyWinAdmin Blog on Facebook Page and Google+ Page.