PowerShell Studio: Comment-Based Help Templates

• Scripting
• Windows PowerShell
• Help

User Rating: 4 / 5

In a previous article we covered how you can generate comment-based help for functions. We expanded upon this feature by adding the ability to create templates for the comment-based help generator.

[Requires: PowerShell Studio 2014 v4.1.61 or above]

Comment-Based Help Templates

PowerShell Studio comes with a predefined template that contains the following:

The template file contains the typical comment-based help block with some token variables and a single parameter section.

When the user generates comment-based help for a function or file, PowerShell Studio will read the template file. Depending on if the function already has comment-based help, it will behave as follows:

If comment-based help is not present:

PowerShell Studio will insert all the sections in order, as defined by the template.

If comment-based help is present:

PowerShell Studio will check whether each section within the template is present in the existing comment and insert if necessary. In addition, the existing comment’s sections will be reordered to match that of the template’s.

Note: Empty sections will not be inserted. For example, if OUTPUTS section in the template above is empty after replacing the variables (the function has no output), PowerShell Studio will ignore it instead of inserting it into the comment.

Parameter Section

The template only contains a single parameter section that defines each new parameter’s text. Notice that there is no parameter name after the section. When PowerShell Studio encounters the Parameter section in the template, it will place all the function’s parameters sequentially within the comment block.

For example, in the template shown above, all the parameters will be inserted after the Description section and before the Example section.

Template Variables

The following are template variables that will dynamically be expanded by PowerShell Studio when a comment section is inserted:

You can also use the standard template variables as well:

Creating a Comment-Based Help Template

Creating a template is easy. Simply right-click on the comment-based help you wish to convert into a template and select the Create Comment-Based Help Template option from the context menu:

Next you are then presented with a file save dialog:

Save the template with your desired name. The resulting template file will be saved as a ps1 file in the following folder:

C:\Users\<username>\AppData\Roaming\SAPIEN\PowerShell Studio [YEAR]\Templates\Comment Help\

If the original comment-based help has one or more parameter sections, PowerShell Studio will automatically format the Parameter section for the template:

Now simply edit the file to include the necessary sections, variables and text. To apply the changes, save the template file as you would normally any normal script.

 You can generate a new template from an existing template using the same procedure described above. For example, you can open PowerShell Studio’s predefined template and use that as a starting point.
 Note: The predefined template is located in the following folder: C:\ProgramData\SAPIEN\PowerShell Studio [YEAR]\Templates\Comment Help

Multiple Templates

PowerShell Studio allows you to define multiple templates, so that you can apply them to specific situations. When more then one template exists, PowerShell Studio will present you with the following selection dialog:

Use the dialog to select the desired template to be applied.

Multi-line Comments or Single Line Comments

The comment-based help templates support either single line comments or multi-line comments. So for those of you who prefer to use single line comments, you can also create a template using single line comments and when applied it automatically converts an existing multi-line comment to single line. If you have a multi-line comment template, it will convert the existing single line comments to a multi-line comment.

Note: A template’s formatting is not taken into account when generating comment-based help.

• Prev
• Next