Try Now

Get-Help! Using Comment-Based Help in PowerShell Scripts

Table of Contents

Post Featured Image

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:

Keywords for Comment-Based Help
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:
Screenshot: Notation of help keywords and content in a script

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.

Screenshot: Example PowerShell function

Example function

The aim now is to describe the functionality by means of descriptions, examples and parameter information in a help article.

Screenshot: meta-data in the function header

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:

PowerShell screenshot: Output of Get-Help Get-ChildItemDepth

Output from Get-Help Get-ChildItemDepth

The -Examples parameter can also be used to output all available examples:

alt="PowerShell Screenshot: Output from Get-Help Get-ChildItemDepth -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 the author: