PowerShell: Function Inline Doc

By Xah Lee. Date: . Last updated: .

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:

#.keyword #text

Block comment can also be used:

<# .keyword text #>

[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 immediately above the function: 

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

or in the beginning of the function block: 

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

or before the end of block: 

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