Powershell Utility: Comment Based Help Automater
Comment based help is used in powershell-land to provide fast and easy help for cmdlets at the console. This little powershell based GUI helps fellow coders automatically construct comment based help blocks for their functions.
About
Comment based help allows you to run ‘get-help ’ at a powershell console to get more information about a cmdlet or function. And it is extremely easy to add comment based help to your own custom powershell functions with a specially formatted comment block just before, or immediately inside of a function.
Unfortunately only a third of powershell functions I’ve come across on the internet have the appropriate comment blocks included with them. This utility aims to make it easier for script writers to add comment based help to their scripts with an easy to use GUI which can automatically capture all the parameters of their function (as well as any specified HelpMessage if it exists).
Version
Version : 1.0.0 May 31th 2013
– First release
Notes
The zip includes a stand-alone ps1 script, a compiled executable of the script, and a folder with all the project files I put together with Sapien Powershell Studio 2012.
The hardest part of this script was converting the text to a script block and trying to figure out all the ways to yank out parameters with [Management.Automation.PSParser]::Tokenize. If you are purely interested in that aspect of the tool you can find the function “Get-FunctionParameters” in the globals.ps1 script with the project files. The one item I’ve not resolved is parsing out a parameter which is of type [ScriptBlock] with a default value set (something with the curly braces but I’ve not put too much effort into this due to its infrequent occurrence).
This utility will only parse a single function at a time. In fact, you only need to supply the param block to get the full results.
Screenshots
Conclusion
I hope that this little tool finds its way into fellow scripter’s utility collections. Give me a holler if you have any ideas for improvement (or improve it yourself!).