Sunday, December 28, 2008

PowerShell CTP3 Comment Based Help

I’ve been playing a lot with comment based help (CBH) in PowerShell CTP3.CBH enables you to decorate a script with help information. This information can then be read by Get-Help to provide help text back to a user of your script. From an enterprise, production scripting point of view, this is very cool and super useful. Production scripts should always be well documented. And for community generated scripts, having great help text will only aid other users trying to integrate these community scripts into their environment.

The CBH information is specified inside a block comment at the start of your script. A block comment begins with  “<# “ and ends with “#>”- everything inside these two character blocks is considered to be a comment. Here’s a very simple CBH block within a script:

# Script CBH-1
     Cool Script 
     No really. It's really really cool"
     Author     : Thomas Lee -
"The meaning of life, the universe and everything is {0}" -f 42 
You can run this script, and it'll produce a predictable output. BUT, if you save it, say as Truth.Ps1, you can then run Get-Help against it, with output as follows:

PS C:\Foo:\> Get-Help  C:\Foo\Truth.ps1
     Cool Script
     C:\Foo\truth.ps1 []
     No really. It's really really cool"
     To see the examples, type: "get-help C:\Foo\Truth.ps1 -examples".     For more information, type: "get-help C:\Users\tfl\AppData\Local\Temp\Untitled19.ps1 -detailed".
     For technical information, type: "get-help C:\Foo\ -full".
PS C:\foo>Get-Help C:\foo\truth.ps1 -Full
NAME     C:\foo\truth.ps1
SYNOPSIS     Cool Script
SYNTAX     C:\Foo\ []
     No really. It's really really cool"
     This cmdlet supports the common parameters: -Verbose, -Debug,
     -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
     -OutBuffer and -OutVariable. For more information, type,
     "get-help about_commonparameters".
         Author     : Thomas Lee -

This is very useful, as I hope you can imagine.

I’ve been doing some digging into this feature. The CTP3 release notes make mention of the various sections that help reports. I’ve built a sample script with what I think to be all the section names used. The idea being that this basic script can be used to demonstrate Get-Help in all its glory. However, what I’ve discovered is a great idea, but with some challenges.
First, here’s my sample auto-help demo script:

    A summary of what this script does
    In this case, this script documents the auto-help text in PSH CTP 3
    Appears in all basic, -detailed, -full, -examples
    A more in depth description of the script
    Should give script developer more things to talk about
    Hopefully this can help the community too
    Appears in basic, -full and -detailed
    Additional Notes, eg
    File Name  : Get-AutoHelp.ps1
    Author     : Thomas Lee -
    Appears in -full
    A hyper link, eg
    Becomes: "RELATED LINKS"
    Appears in basic and -Full
    The first example - just text documentation
    You should provide a way of calling the script, plus expected output
    Appears in -detailed and -full
    The second example - more text documentation
    This would be an example calling the script differently. You can have lots
    and lots, and lots of examples if this is useful.
    Appears in -detailed and -full
   Documentary text, eg:
   Input type  [Universal.SolarSystem.Planetary.CommonSense]
   Appears in -full
   Documentary Text, eg:
   Output type  [Universal.SolarSystem.Planetary.Wisdom]
   Appears in -full


Bernd Kriszio said...

Thanks Thomas.
Good work.

Another issue:
The generated full help displays default values for parameters,
but ignores the usual way to provide default values like
[int64] $foo=42.

Anonymous said...

For the record, the #requires line can be anywhere in your script, so you should just move it to the bottom or something. Make sure there's at least a line of code between the "auto-help" and the:

#requires -version 2.0

However, you're right that in order for the help comments to be parsed, they must be the FIRST comments in the function or script.

MediaAndMicrocode said...

You can also use inline help to generate blog posts automatically:

Details @:

Unknown said...

Great post, Thomas. The help this feature, which we call "comment-based-help" is in about_Comment_Based_Help in PowerShell. You can find it online here:

You can use it to doc functions, scripts, and modules. Details are in the help topic.