Writing Help for PowerShell custom functions

Article
1/17/2024

Summary

During our internal PowerShell discussion, we were assessing the PowerShell functions and enhancement. One thing we missed is to see help sections for the function. The team made very clear comments in the scripting. Indeed, it's good but not great doing it. Best practice is to update the PowerShell help.

Introduction

How to Write a help for custom functions or scripts? There is a quick way of doing it using PowerShell ISE. Press CTRL + J in ISE and choose either Cmdlet advanced function or cmdlet advanced function - Complete.

Pre-formatted Code

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
#>
function Verb-Noun
{
    [CmdletBinding()]
    [OutputType([int])]
    Param
    (
        # Param1 help description
        [Parameter(Mandatory=$true,
                   ValueFromPipelineByPropertyName=$true,
                   Position=0)]
        $Param1,

        # Param2 help description
        [int]
        $Param2
    )

    Begin
    {
    }
    Process
    {
    }
    End
    {
    }
}

Custom Help

Full Code

<#
.Synopsis
   This is a Demo Function to write Simple help
.DESCRIPTION
   This describes how to write help for your PowerShell scripts/functions.
.EXAMPLE
   Get-Service -Running
   Fetch all running services
   Tested in PowerShell 4.0
.EXAMPLE
   Get-Service -Stopped
   Fetch all stopped services
   Tested in PowerShell 4.0
#>
function Get-WindowsServices
{
    [CmdletBinding()]
    [OutputType([int])]
    Param
    (
        # Running help description
        [switch]$Running,

        # Stopped help description
        [switch]
        $stopped
    )

    Begin
    {
        Get-Service
    }
    Process
    {
        if($Running){
        (Get-Service).Where({$_.Status -eq 'Running'})
        }
        if($stopped){
        (Get-Service).Where({$_.Status -ne 'Running'})
        }
    }
    End
    {
    }
}

help Get-WindowsServices -Detailed

help Get-WindowsServices -ShowWindow

help Get-WindowsServices -Examples

Usage

help Get-WindowsServices -Detailed

help Get-WindowsServices -ShowWindow

help Get-WindowsServices -Examples

Enjoy PowerShell :)

Share via