PowerShell Studio: Comment-Based Help Templates
- Written by David Corrales
- Last Updated: 21 April 2016
- Created: 05 June 2014
- Hits: 2801
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.
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.
The following are template variables that will dynamically be expanded by PowerShell Studio when a comment section is inserted:
|%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:
|%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:
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
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.