User Rating: 4 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Inactive
 

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:

.SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE, .OUTPUTS, .NOTES

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:

Variable Description
%NAME% Inserts the name of the function or file.
%TARGETTYPE% Inserts “function” if the comment is for a function.
Inserts “file” if the comment is for a file.
%PARAMETER% Inserts the parameter name (Only valid within the Parameter section).
%EXAMPLE% Inserts a generated example using the existing parameters.
%OUTPUTS% Inserts a list of outputs determined by the Output attribute.

You can also use the standard template variables as well:

Variable Description
%AppName% PowerShell Studio name
%AppVersion% PowerShell Studio version
%Username% The user name specified in the settings.
%Company% The user company name specified in the settings.
%Year% Current Year i.e. 2014
%Date% Current Date i.e. 5/12/2014
%Time% Current Time i.e. 2:17 PM
%FileName% Inserts the file’s name. This will be empty for new non-project files.
%ProjectName% Inserts the file’s project name.
%GUID% Inserts a unique GUID

 

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:

right-click on the comment-based help and select the Create Comment-Based Help Template option from the context menu

Next you are then presented with a file save dialog:

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:

PowerShell Studio automatically formats the Parameter section

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.

Tip 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:

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.

If you have questions about our products, please post in our support forum.
For licensed customers, use the forum associated with your product in our Product Support Forums for Registered Customers.
For users of trial versions, please post in our Former and Future Customers - Questions forum.
Copyright © 2024 SAPIEN Technologies, Inc.