- Courses
- đź’»Programming Languages
- 🪟PowerShell
- PowerShell Scripting at Scale
- Writing Professional Scripts
- Comment-Based Help
On this page
PowerShell Documentation with Comment-Based Help
Updated on June 22, 2026
By Enrico Hochkoeppler
Web Developer & TutoriaLibre Founder
Comment-based help is a foundational element of professional PowerShell scripting. It allows script and function authors to embed structured documentation directly within the source code using special comment keywords. PowerShell's Get-Help cmdlet displays this documentation in the same format as built-in cmdlet help, making it accessible and familiar to all users. This built-in system ensures documentation stays synchronized with code, reduces reliance on external files, and transforms a script from a collection of commands into a professional, self-documenting tool. By consistently including comment-based help, you ensure your scripts are understandable, safe to use, and aligned with industry standards.
What Comment-Based Help Is​
Comment-based help is a block of specially formatted comments placed inside a script or function. PowerShell reads these comments and exposes them through the Get-Help cmdlet. Users can view this help using all standard Get-Help parameters—Detailed, Full, Examples, and Online.
Key benefits:
- Your script behaves like a native PowerShell cmdlet
- Users can run
Get-Help .\MyScript.ps1without opening the file - Documentation stays synchronized with the code
- No external XML or MAML files are required
Get-Helpparameters likeDetailed,Full, andExamplesall work with comment-based help
Comment-based help was introduced with PowerShell 2.0 and has been the standard documentation method for scripts and functions ever since.
Syntax of Comment-Based Help​
Comment-based help is written as a series of comments. You can use either of two syntax styles:
Single-line comment syntax (hash symbol before each line):
# .<help keyword>
# <help content>
Block comment syntax (using <# and #>):
<#
.<help keyword>
<help content>
#>
Each section of the help is defined by a keyword preceded by a dot (.), such as .SYNOPSIS or .DESCRIPTION. Keywords can appear in any order and are not case-sensitive. The help content for each keyword begins on the line after the keyword and can span multiple lines.
Important formatting rules:
- All lines in a comment-based help topic must be contiguous
- If a help topic follows a non-help comment, there must be at least one blank line between them
- A comment block must contain at least one help keyword
- Some keywords, such as
.EXAMPLE, can appear multiple times
Comment-Based Help Keywords​
The following are the valid comment-based help keywords, listed in the order they typically appear in a help topic:
Core Documentation Keywords​
KeywordPurpose.SYNOPSISA brief, one-sentence description of the function or script. Can be used only once..DESCRIPTIONA detailed explanation of the function or script. Can be used only once..PARAMETER <Parameter-Name>The description of a parameter. Include one for each parameter. The order in the param statement determines display order..EXAMPLEA sample command that uses the function or script, optionally followed by output. Repeat for each example..INPUTSThe .NET types of objects that can be piped to the function or script. Repeat for each input type..OUTPUTSThe .NET types of objects that the function or script returns. Repeat for each output type..NOTESAdditional information such as author, version, or requirements..LINKThe name of a related topic. Repeat for each related topic. Can also include a URI for online help.
Advanced Filtering Keywords​
KeywordPurpose.COMPONENTThe technology or feature the function uses. Used by Get-Help -Component..ROLEThe user role for the help topic. Used by Get-Help -Role..FUNCTIONALITYKeywords describing the intended use. Used by Get-Help -Functionality.
Redirection Keywords​
KeywordPurpose.EXTERNALHELPRedirects to an XML-based help file. Takes precedence over all other comment-based help keywords. When present, Get-Help does not display comment-based help even if it cannot find the XML file..FORWARDHELPTARGETNAME <Command-Name>Forwards to the help topic of another command..FORWARDHELPCATEGORYSpecifies the category of the forwarded help target.
Parameter Description Alternative​
You can also specify a parameter description by placing a comment in the param statement immediately before the parameter variable name. If you use both a param statement comment and a .PARAMETER keyword, the .PARAMETER keyword description takes precedence.
Placing Comment-Based Help​
The placement of comment-based help determines whether Get-Help associates the help topic with a script or a specific function.
For Scripts​
Place the help block at the top of the script file, before any executable code. Script help can be preceded only by comments and blank lines.
Important: In a script that does not have a param statement, there must be at least two blank lines between the final comment in the help topic and the first function declaration. Without these blank lines, Get-Help associates the help topic with the function instead of the script.
For Functions​
Comment-based help for a function can be placed in one of three locations:
- At the beginning of the function body (immediately after the opening brace)
- At the end of the function body (before the closing brace)
- Before the
functionkeyword
Note: Placing comment-based help outside a function prevents
Get-Helpfrom working correctly. Help blocks must be inside the function.
Placement Examples​
Function help at the beginning of the function body:
function Add-Extension {
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
.PARAMETER Name
Specifies the file name.
.PARAMETER Extension
Specifies the extension. "Txt" is the default.
#>
param(
[string]$Name,
[string]$Extension = "txt"
)
$Name = $Name + "." + $Extension
$Name
}
Code explanation: The help block is placed immediately after the function declaration and before the param statement. This ensures Get-Help associates the help with the function.
Script help at the top of the file:
<#
.SYNOPSIS
Creates new Active Directory user accounts from a CSV file.
.DESCRIPTION
This script reads user information from a CSV file and creates
Active Directory accounts with standardized attributes.
.PARAMETER Path
The path to the CSV file containing user information.
.EXAMPLE
.\New-ADUsers.ps1 -Path "C:\Data\Users.csv"
.NOTES
Author: Enrico Rossi
Version: 1.3
Requires: ActiveDirectory module
#>
param(
[Parameter(Mandatory)]
[string]$Path
)
# Main script logic follows...
Code explanation: The help block is at the very top of the script file, before any parameters or executable code.
Example of Comment-Based Help for a Script​
Below is a complete, professional help block for a script that creates new users from a CSV file:
<#
.SYNOPSIS
Creates new Active Directory user accounts from a CSV file.
.DESCRIPTION
This script reads user information from a CSV file and creates
Active Directory accounts with standardized attributes. It supports
secure password handling, OU placement, and optional logging.
.PARAMETER Path
The path to the CSV file containing user information. The file must
include Name, SamAccountName, and Password columns.
.PARAMETER LogPath
Optional. If provided, the script writes a log of all created accounts
to the specified file.
.EXAMPLE
.\New-ADUsers.ps1 -Path "C:\Data\Users.csv"
.EXAMPLE
.\New-ADUsers.ps1 -Path "C:\Data\Users.csv" -LogPath "C:\Logs\creation.log"
.NOTES
Author: Enrico Rossi
Version: 1.3
Requires: ActiveDirectory module
.LINK
https://learn.microsoft.com/en-us/powershell/module/activedirectory/
#>
This block provides everything an administrator needs to understand and use the script safely.
Example of Comment-Based Help for a Function​
Functions should also include help, especially if they are part of a module or reused across scripts:
function New-EmployeeAccount {
<#
.SYNOPSIS
Creates a new Active Directory user account.
.DESCRIPTION
This function creates a new AD user with the specified name,
username, and password. It does not enable the account unless
explicitly requested.
.PARAMETER Name
The display name of the user.
.PARAMETER SamAccountName
The logon name for the user.
.PARAMETER Password
A secure string representing the user's password.
.EXAMPLE
New-EmployeeAccount -Name "Alice Kim" -SamAccountName "alice.kim" -Password $pwd
.OUTPUTS
Microsoft.ActiveDirectory.Management.ADUser
.LINK
Get-ADUser
#>
param(
[Parameter(Mandatory)]
[string]$Name,
[Parameter(Mandatory)]
[string]$SamAccountName,
[Parameter(Mandatory)]
[securestring]$Password
)
New-ADUser -Name $Name -SamAccountName $SamAccountName -AccountPassword $Password
}
This ensures that anyone using the function can access help directly.
How PowerShell Uses Comment-Based Help​
Once help is embedded, PowerShell exposes it through the standard help system.
Viewing Help for a Script​
Get-Help .\New-ADUsers.ps1
Viewing Help for a Function​
Get-Help New-EmployeeAccount
Viewing Examples Only​
Get-Help .\New-ADUsers.ps1 -Examples
Viewing Detailed Help​
Get-Help .\New-ADUsers.ps1 -Detailed
Viewing Full Help (All Sections)​
Get-Help .\New-ADUsers.ps1 -Full
Viewing Online Help​
If the .LINK keyword includes a valid URI, users can open it:
Get-Help .\New-ADUsers.ps1 -Online
All standard Get-Help parameters work with comment-based help, making your script feel like a built-in cmdlet.
Best Practices for Writing Comment-Based Help​
To ensure your help is clear and professional:
Write the synopsis as a single, concise sentence. The .SYNOPSIS should be a brief, one-line summary that immediately tells the user what the command does.
Use the description to explain purpose and behavior. The .DESCRIPTION should provide enough detail for a user to understand when and how to use the command.
Document every parameter, even optional ones. Each .PARAMETER keyword should clearly explain what the parameter does, its expected values, and any defaults.
Provide multiple examples covering common scenarios. Each .EXAMPLE should show a realistic command and, optionally, its expected output.
Specify input and output types when applicable. Use .INPUTS and .OUTPUTS to document what objects can be piped in and what the command returns.
Include version, author, and requirements in .NOTES. This helps maintainers understand the script's context and dependencies.
Add .LINK references to related commands or online documentation. This helps users discover additional resources.
Keep help synchronized with script updates. When the script changes, update the help. Outdated help is worse than no help at all.
Explain logic and intent, not just syntax. Focus on why the script exists and what problem it solves.
Use clear, formal language. Avoid abbreviations unless they are standard in your environment.
Refer to the command consistently. In a script help topic, refer to the command as a "script." In a function help topic, refer to it as a "function".
Include at least one or two examples. Even for simple scripts, examples help users understand usage immediately.
Troubleshooting Comment-Based Help​
Help Not Displaying​
If Get-Help does not show your comment-based help:
- Check placement. For functions, the help block must be inside the function (before the
paramblock or at the end of the function body). - Check contiguous lines. All lines in the help topic must be contiguous. Non-help comments inserted between help sections will break the help.
- Check blank lines. For scripts without parameters, there must be at least two blank lines between the help block and the first function declaration.
- Verify the
.EXTERNALHELPkeyword is not present. This keyword preventsGet-Helpfrom displaying comment-based help. - Watch for
#Requiresconflicts. In some PowerShell versions, placing#Requires -PSEdition Coreon the first line of a function can prevent comment-based help from displaying.
Parameters Not Appearing​
If a parameter's help is not showing:
- Ensure the
.PARAMETERkeyword includes the exact parameter name on the same line. - The parameter name must match exactly the parameter in the
paramblock. - If you use a comment in the
paramstatement and a.PARAMETERkeyword, the.PARAMETERkeyword takes precedence.
Syntax Errors​
If the format of a keyword is wrong—for example, forgetting to place the parameter name on the same line as .PARAMETER—the entire help block may not be displayed.
Summary​
Comment-based help is a foundational element of professional PowerShell scripting. It transforms scripts into self-documenting tools by providing:
- Clear explanations of purpose and behavior through
.SYNOPSISand.DESCRIPTION - Detailed parameter documentation with
.PARAMETER - Practical usage examples with
.EXAMPLE - Integration with the
Get-Helpsystem, including all standard parameters likeDetailed,Full,Examples, andOnline - Advanced keywords for filtering (
.COMPONENT,.ROLE,.FUNCTIONALITY) and redirection (.EXTERNALHELP,.FORWARDHELPTARGETNAME)
By consistently including comment-based help, you ensure that your scripts are understandable, safe to use, and aligned with professional standards. This is not optional in professional environments—it is a core requirement that distinguishes well-engineered automation from ad-hoc scripts.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Script Structure Best Practices
Next
Logging Strategies
-
What Comment-Based Help Is
-
Syntax of Comment-Based Help
-
Comment-Based Help Keywords
- Core Documentation Keywords
- Advanced Filtering Keywords
- Redirection Keywords
- Parameter Description Alternative
-
Placing Comment-Based Help
- For Scripts
- For Functions
- Placement Examples
-
Example of Comment-Based Help for a Script
-
Example of Comment-Based Help for a Function
-
How PowerShell Uses Comment-Based Help
- Viewing Help for a Script
- Viewing Help for a Function
- Viewing Examples Only
- Viewing Detailed Help
- Viewing Full Help (All Sections)
- Viewing Online Help
-
Best Practices for Writing Comment-Based Help
-
Troubleshooting Comment-Based Help
- Help Not Displaying
- Parameters Not Appearing
- Syntax Errors
-
Summary
