SAPIEN Technologies

One of my favorite features in PowerShell v2.0 is the ability to add help scripts and functions. The help system with cmdlets is terrific. Type help and the name of a cmdlet and you get syntax, parameters, a description and examples.  In PowerShell v2 you can get this same functionality for your scripts and functions. The example I want to show you will work with PowerShell v2.0 that ships with WIndows 7 Release Candidate. There have been some changes since PowerShell CTP3 so if you want the absolute latest PowerShell bits you’ll need Windows 7. Here’s what you can look forward to.

At the beginning of your script or function you can create a special here string comment block with special “headings”. Here’s an example.

<#

.Synopsis

    This does something really cool

.Description

    Let me explain in a little more detail how cool this really is

    and why you want to use it.

.Parameter Foo

    Describe the first parameter

.Parameter Bar

    Describe the second parameter

.Example

    PS C:\> this -foo goober

    This will do something amazing

.Example

    PS C:\> something | this -bar testing | somethingelse

    In this example, objects are piped from something, piped to this which

    then pipes to somethingelse.

.Inputs

    Accepts strings as pipelined input

.Outputs

    [object]   

.Link

   Get-Something

   Get-Another

   Set-Something

.Notes

 NAME:      Do-Something

 VERSION:   1.0

 AUTHOR:    You

 LASTEDIT:  today

#>

The dotted headings should be self-explanatory. With this information in my script, I can run help .\myscript.ps1 and get output like this:

NAME
    C:\scripts\posh\v2Template.ps1

SYNOPSIS
    This does something really cool

SYNTAX
    C:\scripts\posh\v2Template.ps1 [-Foo] <String[]> [[-bar] <String>] [<CommonParameters>]

DESCRIPTION
    Let me explain in a little more detail how cool this really is
    and why you want to use it.

RELATED LINKS
    Get-Something
    Get-Another
    Set-Something

REMARKS
    To see the examples, type: “get-help C:\scripts\posh\v2Template.ps1 -examples”.
    For more information, type: “get-help C:\scripts\posh\v2Template.ps1 -detailed”.
    For technical information, type: “get-help C:\scripts\posh\v2Template.ps1 -full”.

How cool is that? Using the -full, -detailed and -examples parameters work as well.

PS C:\scripts\posh> help .\v2Template.ps1 -ex

NAME
    C:\scripts\posh\v2Template.ps1

SYNOPSIS
    This does something really cool

    ————————– EXAMPLE 1 ————————–

    PS C:\>this -foo goober

    This will do something amazing

    ————————– EXAMPLE 2 ————————–

    PS C:\>something | this -bar testing | somethingelse

    In this example, objects are piped from something, piped to this which
    then pipes to somethingelse.

The comment block must go at the very beginning of your script. If you have a header or other comments, there must be at least one blank line before the help section.

   1: #requires -version 2.0

   2: #you need at least one blank line before the help

   3:  

   4: <#

   5: .Synopsis

   6:     This does something really cool

   7: .Description

   8:     Let me explain in a little more detail how cool this really is

   9:     and why you want to use it.

In Windows 7 take a look at about_Comment_Based_Help to get all the details.