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