On this page

PowerShell Documentation with Comment-Based Help

Updated on June 22, 2026

Enrico Hochkoeppler Profile

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:

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:


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:

  1. At the beginning of the function body (immediately after the opening brace)
  2. At the end of the function body (before the closing brace)
  3. Before the function keyword

Note: Placing comment-based help outside a function prevents Get-Help from 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:

  1. Check placement. For functions, the help block must be inside the function (before the param block or at the end of the function body).
  2. Check contiguous lines. All lines in the help topic must be contiguous. Non-help comments inserted between help sections will break the help.
  3. Check blank lines. For scripts without parameters, there must be at least two blank lines between the help block and the first function declaration.
  4. Verify the .EXTERNALHELP keyword is not present. This keyword prevents Get-Help from displaying comment-based help.
  5. Watch for #Requires conflicts. In some PowerShell versions, placing #Requires -PSEdition Core on the first line of a function can prevent comment-based help from displaying.

Parameters Not Appearing​

If a parameter's help is not showing:

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:

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!

Buy Me a Coffee

Previous

Script Structure Best Practices

Next

Logging Strategies