Surely you already use comments within your PowerShell scripts, and surely you too have been annoyed by uncommented scripts.
Comments in PowerShell scripts make it possible to document certain processes directly in the code. Furthermore, additional notes can be added to code snippets – for example, if a function is to be extended by further features.
But beyond this pure information content, comments in PowerShell, used correctly, can be used for help articles about your functions. In this article, I’ll show you how to use meta-data to get script information via Get-Help.
Comment-Based Help Keywords
The magic word for our project is Comment-Based Help.
As the name suggests, this method allows us to generate help information through comments. These comments have to be arranged and formatted correctly – you’ll find out exactly how in this section.
In principle, we can distinguish between two types: Comment-Based Help for Functions and for Scripts. The former goes one layer deeper and starts with functions, which we want to provide with meta-data. However, if your code is not prepared in functions, it is also possible to provide a whole script with this information.
Before we look at their exact usage, I list all keywords for the Comment-Based Help here:
| KEYWORD | FUNCTION |
| SYNOPSIS | Short description of the script or function |
| DESCRIPTION | Detailed description of the code |
| PARAMETER | Description of a used parameter. Keyword is used several times (1x per parameter). The parameter must be named additionally after the keyword! |
| INPUTS | Description of possible objects that can be passed into the function via a pipeline. |
| OUTPUTS | Output values of the function |
| NOTES | Additional information about the code |
| LINK | URL to the corresponding online help (if available) |
In order not to go beyond the scope of this article, I will limit the listing to the keywords that are used most often. You can find more keywords in the Microsoft Docs.
Note: Script header information also plays an important role for the use of scripts in the ScriptRunner software platform. You can read more about it here: PowerShell Script Headers and Parameters for use in ScriptRunner.
Using Comment-Based Help
The keywords listed above are notated in a specific format in the code. This looks like the following:
Notation of Help Keywords and Content in the PowerShell Script Header
The keywords are headed with a period – the corresponding text is placed below the keyword. The keyword block is commented out using “<##>”.
Comment-Based Scripts and Functions differ in the sense that the Comment block is placed differently. For functions, it is best to place the block under the function name. Other possibilities are to place the block directly in front of the function (without a blank line) or at the end of the function body.
If scripts are to be equipped with the information, the Comment block is set directly at the beginning of the code – logically, this then also contains information about the script as a whole and not about partial sections.
Example and Usage of Comment-Based Help
In the following, we will show how Comment-Based Help can be used in practice by means of a function that outputs all directory and file objects of a certain directory up to a certain hierarchy depth.
PowerShell already provides this functionality – the following example only serves for understanding.
Example function
The aim now is to describe the functionality by means of descriptions, examples and parameter information in a help article.
Meta-data in the function header
In this code a holistic help comment has now been written. On a Get-Help call on this information, we now get the following output in the console:
Output from Get-Help Get-ChildItemDepth
The -Examples parameter can also be used to output all available examples:
Output of the examples stored in the script
Tip: For more examples of scripts built according to PowerShell best practices, take a look at our ScriptRunner ActionPacks.
Conclusion
In principle, it can be said that Comment-Based Help offers great benefits for IT departments. Not only can you get a quick overview of the self-built functions yourself, but colleagues don’t have to fight their way through numerous lines of code to guess the basic functionality.
Due to its limited length, the script name can only ever give a rough indication of a script’s function without being able to go into detailed information. This way of creating help also saves the need for external documentation of the code.
If there is a basic policy or code-of-conduct that explicitly requires the use of these help sections, I can strongly recommend the Pester module. It can be configured to check the code for the presence of help articles before each release. You can even check if every single parameter has a description.
Related Links
- about Comment Based Help – PowerShell | Microsoft Docs
- PowerShell Script Header and Parameters for Use in ScriptRunner | ScriptRunner Blog
- ActionPacks – Free PowerShell Script Collections | ScriptRunner
- Introduction to Pester – Part 1 | ScriptRunner Blog
Related Posts
About the author:
Philip Lorenz was trained at a large fashion company in Germany and then worked as a specialist for data center and cloud. The focus here was on VMware, Windows Server and Microsoft Azure. His core competence is automating these platforms with PowerShell. Currently, Philip is in a dual study program to become a business information scientist and has built up his own business by providing PowerShell courses, PowerShell coaching and freelancing.