Can you provide additional help for common parameters in a PowerShell script?

user_13630037 0
Viewed 63

I wrote a script which uses Write-Verbose and the common parameter -verbose. Now I would like to give the user additional information about what happens when they specify -verbose via Get-Help. I tried to do it like regular parameters, but when I run Get-Help in the script it doesn't get picked up.

<#
.PARAMETER verbose
Help text for Get-Help
#>

Is there some way to nicely present the help text or do I have to "abuse" .DESCRIPTION?

parameters powershell
3 Answers

I don't think it's possible and you seem to have confirmed that.

Rather than use DESCRIPTION I might consider NOTES as a section where you could include this information.

Alternatively, if adding -Verbose primarily affects the operation of one existing parameter, it may be best to include the information in that parameter's inline help.

One other thing I'll note: you probably don't want that information to be associated with the -Verbose parameter anyway, as that's not the only way that verbose output will be shown.

If the caller set $VerbosePreference to see verbose output for example, the -Verbose parameter will not be bound, however the conditions will still be correct to show it.

user_39050790

An advanced function defined by either the [CmdletBinding] attribute or at least one parameter decorated with [Parameter] attribute already includes the common parameters so you can't define it again.

If you make it a simple function instead of an advanced function, you can define it separately.

function Test-Function {

    <#
        .PARAMETER verbose
        Additional help text for Get-Help
    #>

    param (
        [switch]
        $Verbose
    )
    
    begin {
        
    }
    
    process {
        
    }
    
    end {
        
    }
}

Get-Help Test-Function -Full

It is generally not a good idea to use automatic/reserved variable names.

enter image description here

user_40853310

The common parameters (Verbose included) is a defined set of words that apply to all scripts, these also have their own sections in the predefined commandbased help. Unless there is a way to change this output via custom controls (with formating files ), you will have to get around this with the ordinary parameters of the comment based help

user_40666460
Related