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

Question

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?

[Yes](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-3.0). — Ansgar Wiechers, Oct 17 '18 at 20:53

FoxDeploy · Accepted Answer · 2018-10-17T21:16:48.663

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:

Before the function declaration
After the function declaration(ewww)
At the end of your function (not to be opininonated, but it is morally wrong to choose this option).

The docs give examples of each of the approved locations here as well.

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

1 Answers1