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