Use the Get-Help cmdlet to display comment-based help in the same format

Question

I am trying to use the Get-Help cmdlet to display comment-based help in the same format in which it displays the cmdlet help topics that are generated from XML files. The ability to do this is documented in about_Comment_based_Help on TechNet, but when I execute the get-help cmdlet against my script I only get the script name returned. Any help would be appreciated!

PS C:\Admin> Get-Help .\checksystem.ps1 -full
checksystem.ps1

checksystem.ps1 script:

function IsAlive {
        <#
        .DESCRIPTION
        Checks to see whether a computer is pingable or not.

        .PARAMETER computername
        Specifies the computername.

        .EXAMPLE
        IsAlive -computername testwks01

        .NOTES
        This is just an example function.
        #>


            param (
                $computername
            )
            Test-Connection -count 1 -ComputerName $computername -TimeToLive 5 |
            Where-Object { $_.StatusCode -eq 0 } |
            Select-Object -ExpandProperty Address
        }

IsAlive -computername 192.168.1.1

Andy Schneider · Accepted Answer · 2018-07-08T16:22:42.820

18

It will work, but you are trying to run get help on the script. You have added the help to the function. If you dot source your script, and then type get-help isalive, you will see your help for the function.

. .\checksystem.ps1 ; get-help isalive -full

edited Jul 08 '18 at 16:22

answered Jan 12 '11 at 23:12

Andy Schneider

8,516
6
36
52

score 12 · Answer 2 · answered Jan 12 '11 at 22:20

It works, you just gotta make sure you have the right headings. I've always put the comment block right above the function too. I'm not sure if it's supposed to work inside of the function or not.

Below is an example of one of my functions that has a working doc help.

##############################################################################
#.SYNOPSIS
# Gets a COM object from the running object table (ROT) similar to GetObject
# in Visual Basic.
#
#.DESCRIPTION
# To maintain consistency with New-Object this cmdlet requires the -ComObject
# parameter to be provided and the TypeName parameter is not supported.
#
#.PARAMETER TypeName
# Not supported, but provided to maintain consistency with New-Object.
#
#.PARAMETER ComObject
# The ProgID of a registered COM object, such as MapPoint.Application.
#
#.PARAMETER Force
# If an existing object is not found, instead of writing an error, a new
# instance of the object will be created and returned.
#
#.EXAMPLE
# $olMailItem = 0
# Get-Object -ComObject Outlook.Application | %{$_.CreateItem($olMailItem).Display()}
##############################################################################
function Get-Object {

    [CmdletBinding(DefaultParameterSetName='Net')]
    param (

        [Parameter(ParameterSetName='Net', Position=1, Mandatory=$true)]
        [String]$TypeName,

        [Parameter(ParameterSetName='Com', Mandatory=$true)]
        [String]$ComObject,

        [Parameter()]
        [Switch]$Force

    )

    if ( $TypeName ) { throw '-TypeName is not supported. Use -ComObject instead.' }

    if ( $ComObject ) { 
        try {
            [System.Runtime.InteropServices.Marshal]::GetActiveObject($ComObject)
        }
        catch [System.Management.Automation.MethodInvocationException] {
            if ( $Force ) { New-Object -ComObject $ComObject }
            else { Write-Error "An active object of type $ComObject is not available." }
        }
    }

}

In PowerShell version 3 the comments work both inside and outside of a function: http://technet.microsoft.com/en-us/library/dd819489.aspx — Daniel Flippance, Aug 22 '13 at 18:36
Even better, in PowerShell 3, you don't even need to mark up the parameter help. Just put a regular comment above the parameter and PowerShell figures it out. — Josh, Aug 23 '13 at 19:27
According to this http://technet.microsoft.com/en-us/library/dd819489.aspx comments outside the function applies to powershell 2.0 too. — Raj, Jul 17 '14 at 11:20

score 6 · Answer 3 · edited Dec 04 '13 at 11:59

6

Note - If you forget to add the name of a parameter after .PARAMETER, none of your custom help text will show when you run get-help

Similarly, if you misspell any of the keywords the custom help will not be displayed.

edited Dec 04 '13 at 11:59

David Martin

11,764
1
61
74

answered Aug 22 '13 at 18:40

Daniel Flippance

7,734
5
42
55

Use the Get-Help cmdlet to display comment-based help in the same format

3 Answers3

Linked