PowerShell: Function Inline Doc

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 that is a dot followed by a certain keywords.

Example:

Block comment can also be used:

[see Comment Syntax]

Help Comment Keywords

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

.DESCRIPTION

Most useful.

.SYNOPSIS

Best not use. Let it auto generate.

.PARAMETER

Best not use. Let it auto generate.

.EXAMPLE

Can have multiple.

.INPUTS

description.

.OUTPUTS

description.

.NOTES

notes.

.LINK

A URL.

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.
}