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

Answer 1

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

Answer 2

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." }
        }
    }

}

Answer 3

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.