powershelldocumentation-generationpowershell-5.0powershell-v5.1

How to define documentation on custom command (using Get-Command or Get-Help)


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?


Solution

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