Powershell Script - Comment-Based Help Template (Powershell v2)
9/20/2013: Another frequently useful, but occasionally fiddly, feature of Powershell (as of revision 2), is the Comment-Based Help system. The features intention is to make it quick & easy to include the proper values within your script to provide self-assembling get-help output, to make your script as well-documented for other users, as the stock Powershell Cmdlets.
Unfortunately, the area that most frequently breaks when trying to use what I'll refer to as 'CBH', is in the specifics of formatting and placement and exactly which of the various options you may want to include in most of your scripts.
Like a lot of folks I spent some time poking around in the docs and on the web, and figured out the details to make things function, and generally distilled that material down into a simple boilerplate 'Template' that I use within in every new script I write. And since my goal is is to 'share' with the world, I figured I'd post up my template, along with some useful notes on keeping it functioning trouble-free. :)
Here's a Gist with the key chunks of code (see the full Git copy of the script for more details)
And the current revision can always be found at Github: comment-based-help-template-Psv2.ps1
Comment-Based Help Notes:
ALWAYS INDENT KEYWORDS WITH SPACES NOT TABS: For Keywords, the period must be the first character on the line,excepting spaces or # (hashmark). NO LEADING TABS!
A blank line must appear between any unrelated leading comments, and the start of the CBH <#...#> block:
Within Comment-Blocks(<#...#>) a .KEYWORD must be the first item on the line immediately below the opening <#
No comments:
Post a Comment
Note: Only a member of this blog may post a comment.
No comments:
Post a Comment
Note: Only a member of this blog may post a comment.