Friday, September 20, 2013

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. :)



Todd's Comment-Based Help Template

 
#*----------V Comment-based Help (leave blank line below) V---------- 

<# 
    .SYNOPSIS
[NAME].ps1 - [1-LINE-DESC]

    .NOTES
Written By: Todd Kadrie
Website: http://tinstoys.blogspot.com
Twitter: http://twitter.com/tostka

Additional Credits: [REFERENCE]
Website: [URL]
Twitter: [URL]

Change Log
[VERSIONS]

    .DESCRIPTION
[DESC]

    .PARAMETER  <Parameter-Name>
<parameter comment>

    .INPUTS
None. Does not accepted piped input.

    .OUTPUTS
None. Returns no objects or output.
System.Boolean
                True if the current Powershell is elevated, false if not.
[use a | get-member on the script to see exactly what .NET obj TypeName is being returning for the info above]

    .EXAMPLE
.\[SYNTAX EXAMPLE]
[use an .EXAMPLE keyword per syntax sample]

    .LINK
< name of a related topic, one .LINK keyword per related topic. Can also include a URI to online help (start with http:// or https://)>
*----------^ END Comment-based Help  ^---------- #>



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