PowerShell Studio: Comment-Based Help

• Scripting
• Windows PowerShell
• Help

When creating comment-based help in older versions (prior to 2014) of PowerShell Studio, 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.

As of 2014, PowerShell Studio has the capability to automatically generate comment blocks for existing functions. You can generate comment-based 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:

The Generate Comment Based 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 and 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’s PrimalSense:

At some 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 feature will help users save time and promote the use of help comments in their script.

• Prev
• Next