<<< Back to Search

Scripting ::: Comment Help

Document your functions and scripts and make available this info through the PowerShell Help engine by writing comment-based help.

Locate comment help at the beginning of your function or script.
Parameters can be comented above its definition to be included when help is retrieved

Core Snippet

# Core Snippet

# Scripting ::: Comment Help -_-
# www.PowerShellExamples.com

<#
.SYNOPSIS
    A short one-line action-based description, e.g. 'Tests if a function is valid'
.DESCRIPTION
    A longer description of the function, its purpose, common use cases, etc.
.NOTES
    Information or caveats about the function e.g. 'This function is not supported in Linux'
.LINK
    Specify a URI to a help page, this will show when Get-Help -Online is used.
.EXAMPLE
    Test-MyTestFunction -Verbose
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
#>


    

Practical Sample

Copy code below into a power shell session and execute

# Sample : Scripting ::: Comment Help -_-
# PowerShellExamples.com

function Myfunction {

<#
.SYNOPSIS
    A short one-line action-based description, e.g. 'Tests if a function is valid'
.DESCRIPTION
    A longer description of the function, its purpose, common use cases, etc.
.NOTES
    Information or caveats about the function e.g. 'This function is not supported in Linux'
.LINK
    Specify a URI to a help page, this will show when Get-Help -Online is used.
.EXAMPLE
    Test-MyTestFunction -Verbose
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
#>



Param(
    # Document every Parameter in line above, like this sample
    [string]$MyParam
)

    Write-Host "Sample Line"

}

# After use Comment help, get/retrieve the information using PowerShell Help Engine in the command get-help

Write-Host ">>> Use -Examples to see only Examples" -ForegroundColor Magenta
Get-Help Myfunction -Examples

# Note in -Detailed and -full modes how Parameter comment is presented on the respective parameter information
Write-Host ">>> Use -Detailed to see more info like Parameter Definitions" -ForegroundColor Magenta
Get-Help Myfunction -Detailed

Write-Host ">>> Use -full to see all documentation" -ForegroundColor Magenta
Get-Help Myfunction -Full



Results

PS C:\>

>>> Use -Examples to see only Examples

NAME
    Myfunction
    
SYNOPSIS
    A short one-line action-based description, e.g. 'Tests if a function is valid'
    
    
    -------------------------- EXAMPLE 1 --------------------------
    
    PS C:\>Test-MyTestFunction -Verbose
    
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
 
 

PS C:\>

>>> Use -Detailed to see more info like Parameter Definitions

NAME
    Myfunction
    
SYNOPSIS
    A short one-line action-based description, e.g. 'Tests if a function is valid'
    
    
SYNTAX
    Myfunction [[-MyParam] <String>] [<CommonParameters>]
    
    
DESCRIPTION
    A longer description of the function, its purpose, common use cases, etc.
    

PARAMETERS
    -MyParam <String>
        Document every Parameter in line above, like this sample
        
    <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). 
    
    -------------------------- EXAMPLE 1 --------------------------
    
    PS C:\>Test-MyTestFunction -Verbose
    
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
    
    
    
    
REMARKS
    To see the examples, type: "get-help Myfunction -examples".
    For more information, type: "get-help Myfunction -detailed".
    For technical information, type: "get-help Myfunction -full".
    For online help, type: "get-help Myfunction -online"

 
 

PS C:\>

>>> Use -full to see all documentation

NAME
    Myfunction
    
SYNOPSIS
    A short one-line action-based description, e.g. 'Tests if a function is valid'
    
    
SYNTAX
    Myfunction [[-MyParam] <String>] [<CommonParameters>]
    
    
DESCRIPTION
    A longer description of the function, its purpose, common use cases, etc.
    

PARAMETERS
    -MyParam <String>
        Document every Parameter in line above, like this sample
        
        Required?                    false
        Position?                    1
        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
    
NOTES
    
    
        Information or caveats about the function e.g. 'This function is not supported in Linux'
    
    -------------------------- EXAMPLE 1 --------------------------
    
    PS C:\>Test-MyTestFunction -Verbose
    
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
    
    
    
    
    
RELATED LINKS
    Specify a URI to a help page, this will show when Get-Help -Online is used.