Previously, when creating comment based help in PowerShell Studio 2012, you either had to manually add the help comment or use the built-in comment based help snippet. The snippets worked well but you were still required to manually add each parameter of the function which takes time and there are better ways we would rather spend our time than writing help comments.
One of the new features we added into PowerShell Studio 2014 is the capability to automatically generate comment blocks for existing functions. You can generate comment base help for an existing function by:
1. Using the function explorer’s context menu:
2. Using the editor. Right click on the function’s declaration or the param keyword and bring up the context menu:
Generate Comment Base Help command will insert a help comment tailored to the specific function. The comment will include a .PARAMETER entry for each parameter declared in the function, include an .EXAMPLE entry and add any applicable output entry:
You will still need to supply the descriptive text (it can’t do everything for you) but the structure is there for you to update and edit.
If needed, you can expand on the help comment with the help of PowerShell Studio 2014’s PrimalSense:
At one point, you may add a new parameter to an existing function and need to update the help comment. By calling Generate Help Comment again, it will take any existing help comment and append any missing parameters to the comment block:
We hope that this new feature will help users save time and promote the use of help comments in their script.