PowerShell: Function Inline Doc

Comment Based Help

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

Some part of the doc is auto generated.

Microsoft call this document system “Comment based help”.

# example of function with Comment Based Help

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

When you type help f, it shows like this:

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.

#.KEYWORD
#some thing

# Block comment can also be used:

<#
.KEYWORD
some thing
#>

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

Help Comment Position

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