Comment-based help in PowerShell

Introduction

Comment-based help lets you add instructions inside your PowerShell scripts. It helps others understand what your script or function does.

You write a script and want to explain what it does.

You create a function and want to show how to use it.

You want to provide examples inside your script for users.

You want to add details about parameters your script accepts.

You want to make your script easier to maintain and share.

Syntax

PowerShell

<#
.SYNOPSIS
Short description of the script or function.
.DESCRIPTION
Longer explanation.
.PARAMETER ParameterName
Description of a parameter.
.EXAMPLE
Example of how to use the script or function.
#>

Use <# to start and #> to end the comment-based help block.

Each section starts with a dot and uppercase keyword like .SYNOPSIS or .PARAMETER.

Examples

This example shows a simple synopsis for a script that prints a message.

PowerShell

<#
.SYNOPSIS
Prints Hello World.
#>
Write-Output "Hello World"

This example shows help for a function with parameters and an example usage.

PowerShell

<#
.SYNOPSIS
Adds two numbers.
.PARAMETER a
First number.
.PARAMETER b
Second number.
.EXAMPLE
Add-Numbers -a 3 -b 5
#>
function Add-Numbers {
  param($a, $b)
  $a + $b
}

Sample Program

This script defines a function with comment-based help. It greets the user by name.

PowerShell

<#
.SYNOPSIS
Greets a user by name.
.DESCRIPTION
This function takes a name and prints a greeting message.
.PARAMETER Name
The name of the person to greet.
.EXAMPLE
Greet-User -Name "Alice"
#>
function Greet-User {
  param(
    [string]$Name
  )
  Write-Output "Hello, $Name!"
}

Greet-User -Name "Alice"

Important Notes

Use comment-based help to make your scripts self-explanatory.

You can view the help by running Get-Help FunctionName in PowerShell.

Keep descriptions short and clear for easy understanding.

Summary

Comment-based help adds useful instructions inside scripts.

It uses special comment blocks with sections like SYNOPSIS and PARAMETER.

It helps users understand and use your scripts correctly.