Let's say I have a custom command:
function Search-ForStringInFile($string)
{
ls -Recurse | Select-String -Pattern "$string" -List | Select Path
}
And I want to be able to run Get-Help Search-ForStringInFile
or Get-Command Search-ForStringInFile
to get a description of what the command does.
Description: Searches for keyword in all files in / under current directory
Is there special comment syntax I can use on the function
to add this documentation?
This is called Comment based help. The PowerShell ISE has a really great snippet for doing exactly what you want to do, in fact. Simply hit Control+J and choose 'Cmdlet - Advanced Function' to load a snippet I'll provide below:
<#
.Synopsis
Short description
.DESCRIPTION
Long description
.EXAMPLE
Example of how to use this cmdlet
.EXAMPLE
Another example of how to use this cmdlet
#>
function Verb-Noun
{
}
Once you fill in values for each of these above (see the docs here for all of the available fields) and hit F5, help will appear within your function.
PS>Get-Help Verb-Noun
NAME
Verb-Noun
SYNOPSIS
Short description
SYNTAX
Verb-Noun [-Param1] <Object> [-Param2 <Int32>] [-WhatIf] [-Confirm] [<CommonParameters>]
Verb-Noun [-Param3 <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
DESCRIPTION
Long description
PARAMETERS
-Param1 <Object>
Param1 help description
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false
-Param2 <Int32>
Param2 help description
Required? false
Position? named
Default value 0
Accept pipeline input? false
Accept wildcard characters? false
-Param3 <String>
Param3 help description
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
Required? false
Position? named
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
Inputs to this cmdlet (if any)
OUTPUTS
Output from this cmdlet (if any)
NOTES
General notes
-------------------------- EXAMPLE 1 --------------------------
PS C:\>Example of how to use this cmdlet
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Another example of how to use this cmdlet
RELATED LINKS
So, to add help to your own cmdlet, you simply need to stick that same comment block in your function. You can place it in one of three spots:
The docs give examples of each of the approved locations here as well.