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
#>