PowerShell: Function Inline Doc

By Xah Lee. Date: .

A function can have embedded documentation. When user type help function-name, the documentation will show it.

Example:

function f {
# .DESCRIPTION
# Add two numbers.
param ($x , $y)
$x + $y
}

When you type help f, it shows like this:

PS C:\Users\xah> help f

NAME
    f

SYNOPSIS

SYNTAX
    f [[-x] <Object>] [[-y] <Object>] [<CommonParameters>]

DESCRIPTION
    Add two numbers.

PARAMETERS
    -x <Object>

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -y <Object>

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

INPUTS

OUTPUTS

RELATED LINKS

PS C:\Users\xah>

Some part of the doc is auto generated.

Microsoft call this document system “Comment based help”.

Help Comment Syntax

In order to be recognized as a help text, the comment must start with a line of this form .keyword. Example:

<# .keyword text #>

Line comment can also be used:

#.keyword #text

[see PowerShell: Comment Syntax]

Help Comment Keywords

The following are most important keywords. (there are few others more esoteric.)

The comment can appear in the beginning of the function block:

function f {
#.DESCRIPTION
#Add two numbers.
param ($x , $y)
$x + $y
}

or immediately above the function:

# .DESCRIPTION
# Add two numbers.
function f {
param ($x , $y)
$x + $y}

or before the end of block:

function f {
param ($x , $y)
$x + $y
#.DESCRIPTION
#Add two numbers.
}

PowerShell

How-to

Advanced

Script Examples