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
<# .SYNOPSIS
     Cool Script 
.DESCRIPTION
     No really. It's really really cool"
.NOTES
     Author     : Thomas Lee - tfl@psp.co.uk
.LINK
     http://tfl09.blogspot.com
#>
"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
NAME
     C:\foo\truth.ps1
SYNOPSIS
     Cool Script
SYNTAX
     C:\Foo\truth.ps1 []
DETAILED DESCRIPTION
     No really. It's really really cool"
RELATED LINKS http://tfl09.blogspot.com
REMARKS
     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\Truth.ps -full".
PS C:\foo>Get-Help C:\foo\truth.ps1 -Full
NAME     C:\foo\truth.ps1
SYNOPSIS     Cool Script
SYNTAX     C:\Foo\Truth.ps []
DETAILED DESCRIPTION
     No really. It's really really cool"
PARAMETERS
     This cmdlet supports the common parameters: -Verbose, -Debug,
     -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
     -OutBuffer and -OutVariable. For more information, type,
     "get-help about_commonparameters".
 INPUT TYPE
 RETURN TYPE
 NOTES
         Author     : Thomas Lee - tfl@psp.co.uk
RELATED LINKS http://tfl09.blogspot.com

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:

<#
.SYNOPSIS
    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
.DESCRIPTION
    A more in depth description of the script
    Should give script developer more things to talk about
    Hopefully this can help the community too
    Becomes: "DETAILED DESCRIPTION"
    Appears in basic, -full and -detailed
.NOTES
    Additional Notes, eg
    File Name  : Get-AutoHelp.ps1
    Author     : Thomas Lee - tfl@psp.co.uk
    Appears in -full
.LINK
    A hyper link, eg
    http://www.pshscripts.blogspot.com
    Becomes: "RELATED LINKS"
    Appears in basic and -Full
.EXAMPLE
    The first example - just text documentation
    You should provide a way of calling the script, plus expected output
    Appears in -detailed and -full
.EXAMPLE
    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
.INPUTTYPE
   Documentary text, eg:
   Input type  [Universal.SolarSystem.Planetary.CommonSense]
   Appears in -full
.RETURNVALUE
   Documentary Text, eg:
   Output type  [Universal.SolarSystem.Planetary.Wisdom]
   Appears in -full
.COMPONENT
#>

4 comments:

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 @:

http://blogs.msdn.com/powershell/archive/2008/12/24/write-commandblogpost.aspx

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: http://technet.microsoft.com/en-us/library/dd819489.aspx.

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


Thanks,
juneb