The most efficient way to write help for your Advanced Functions or your own CmdLets is to have a template as a starting point that you will fill out for the script that you have just finished writing the code.
Even better if you can insert that template whenever you want just by few mouse clicks or using keyboard shortcut right from Microsoft Windows PowerShell ISE environment.
That is exactly what we going to learn in this article using PowerShell ISE Add-Ons.
If you want to be super professional in your scripting work you should always document your work when writing Advanced Functions or own CmdLets and provide help for your clients and users of your scripts and at the end, for yourself, since we all have a tendency to forget what we have done once in the past.
Let me quickly show you one example of how you can get a comment-based help template the easy and fast way and then I will explain to you how to achieve the same level of efficiency yourself.
“Give Me Warp Speed, Mr. Sulu”
Star Treks
Table of Contents
Example Of PowerShell Advanced Function’s Help
Open Windows PowerShell ISE and in the empty Script Pane go to menu
Add-ons -> Click on Insert comment block menu item or just press shortcut for same command Ctrl + Alt + C
Here is the result that we get.
<#
.SYNOPSIS
.DESCRIPTION
.PARAMETER
.EXAMPLE
.INPUTS
.OUTPUTS
.NOTES
FunctionName :
Created by : dekib
Date Coded : 10/07/2019 21:19:40
.LINK
Home
#>
IMPORTANT: If we have already written Advanced Function or CmdLet code and we want just to create help for that code we open the script put the cursor at the place where we want to insert the help template and press Ctrl + Alt + C
The comment-based help template will be inserted in the already existing script code.
IMPORTANT: I cannot emphasize this enough but it is VERY VERY important where you put your comment-based code. For a function, we have basically three locations:
- At the beginning of the function body.
- At the end of the function body.
- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword.
TIP: I usually put my comment-based help syntax code just above the Function declaration (keyword). That is the most convenient location at least for me.
UPDATE: Make sure not to make a mistake that I was previously doing and that is to put your comment-based help syntax between own “help” region for readability reasons due to the fact that this will break the rule of where and how comment-based help syntax needs to be placed within the script, module or function.
This is correct example without use of PowerShell regions
<#
.SYNOPSIS
Inserts a full comment block
.DESCRIPTION
This function inserts a full comment block that is formatted the
way I format all my comment blocks.
.PARAMETER InstallMenu
Specifies if you want to install this as a PSIE add-on menu
.EXAMPLE
New-CommentBlock -InstallMenu $true
#>
This is wrong example using the PowerShell regions that will stop showing PowerShell comment-based help
#region help
<#
.SYNOPSIS
Inserts a full comment block
.DESCRIPTION
This function inserts a full comment block that is formatted the
the way I format all my comment blocks.
.PARAMETER InstallMenu
Specifies if you want to install this as a PSIE add-on menu
.EXAMPLE
New-CommentBlock -InstallMenu $true
#>
#endregion
What Did We Get?
We got a comment based template to document our script and this is an excellent starting point.
<#
.SYNOPSIS
.DESCRIPTION
.PARAMETER
.EXAMPLE
.INPUTS
.OUTPUTS
.NOTES
FunctionName :
Created by : dekib
Date Coded : 10/07/2019 21:19:40
.LINK
Home
#>
What Do We Need To Do Next?
- We need to fill out each section (SYNOPSIS, DESCRIPTION, PARAMETER…) of commented help for a particular script.
- We can copy the PARAMETER section if we have more than one input parameter in the function.
- We can copy the EXAMPLE section as well if we want to show more than one example of how to run our function.
New-CommentBlock CmdLet Explained
In order for the previous example to work for you, you need New-CommentBlock CmdLet in your PowerShell environment to be loaded every time you start Windows PowerShell ISE.
We will look into the code of New-CommentBlock CmdLet in a second but first, let me credit the person who wrote that function.
I would really like to thank Jeff Patton for writing a collection of functions in PSISELibrary.ps1 that you can download here.
If you want to follow me along while I describe the function please download the zip file with the source code from here.
New-CommentBlock CmdLet source code is located in …/Modules/09addons/ folder and is part of CmdLet libraries that I have written and named Efficiency Booster PowerShell Project with the intention to help us IT people in our day to day IT tasks.
At the bottom of this article, there is source code of the New-CommentBlock for those who don’t want to download the zip file. Jump to that location by clicking this link.
Even the Function that is helping us to write comment-based help for our own functions is no exception and it has its own comment-based help. We have comment-based help that explains to users how to use New-CommentBlock CmdLet.
REMINDER: Just notice that comment-based help syntax code is placed just above the Function keyword as it should be in one of the three locations explained at the top of this article.
<#
.SYNOPSIS
Inserts a full comment block
.DESCRIPTION
This function inserts a full comment block that is formatted the
way I format all my comment blocks.
.PARAMETER InstallMenu
Specifies if you want to install this as a PSIE add-on menu
.EXAMPLE
New-CommentBlock -InstallMenu $true
Description
-----------
Installs the function as a menu item.
.NOTES
FunctionName : New-CommentBlock
Created by : Jeff Patton
Date Coded : 09/13/2011 13:37:24
Modified by : Dejan Mladenovic
Date Modified : 02/09/2019 01:19:10
More info : http://improvescripting.com/
.LINK
How To Write PowerShell Function’s Or CmdLet’s Help (Fast)
https://gallery.technet.microsoft.com/scriptcenter/PSISELibraryps1-ec442972
#>
We have [CmdletBinding()] attribute which allows the use of PowerShell common parameters (Debug (db), ErrorAction (ea), ErrorVariable (ev), Verbose (vb), etc) with this function.
Function New-CommentBlock
{
[CmdletBinding()]
Within param() construct we have only one input parameter for this function:
- $InstallMenu (It is a switch parameter if true it will add New-CommentBlock to the Windows PowerShell ISE Add-on Menu Item if false it will create the comment-based help with template content)
Param
(
$InstallMenu
)
BEGIN block runs only once and do two things:
- First creates a $CommentBlock variable that holds our comment-based help template code. Here is the right spot to change that template if you need additional customization.
- It adds New-CommentBlock as Add-on Menu Item in Windows PowerShell ISE. Runs only once when we load this CmdLet via PowerShell profile.
Begin
{
$CommentBlock = @(
" <#`r`n"
" .SYNOPSIS`r`n"
" .DESCRIPTION`r`n"
" .PARAMETER`r`n"
" .EXAMPLE`r`n"
" .INPUTS`r`n"
" .OUTPUTS`r`n"
" .NOTES`r`n"
" FunctionName : `r`n"
" Created by : $($env:username)`r`n"
" Date Coded : $(Get-Date)`r`n"
" .LINK`r`n"
" http://improvescripting.com/`r`n"
" #>`r`n")
if ($InstallMenu)
{
Write-Verbose "Try to install the menu item, and error out if there's an issue."
try
{
$psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add("Insert comment block",{New-CommentBlock},"Ctrl+Alt+C") | Out-Null
}
catch
{
Return $Error[0].Exception
}
}
}
PROCESS block (This is the code responsible for all the magic happening)
- NOTE: When the $InstallMenu variable (input parameter) is True this piece of code is not run. We set the $InstallMenu input parameter to True only when we want this function to be added to PowerShell ISE Add-ons Menu.
- Otherwise, the code will insert the Comment-Based Help Template content into the current Tab of the Script Panel.
Process
{
if (!$InstallMenu)
{
Write-Verbose "Don't insert a comment if we're installing the menu"
try
{
Write-Verbose "Create a new comment block, return an error if there's an issue."
$psISE.CurrentFile.Editor.InsertText($CommentBlock)
}
catch
{
Return $Error[0].Exception
}
}
}
END block is empty
End
{
}
Finally, in the Execution examples region, we run the New-CommentBlock with InstallMenu parameter true in order to add this function to the Windows PowerShell ISE Add-on Menu as Menu Item.
#region Execution examples
New-CommentBlock -InstallMenu $true
#endregion
How To Add New-CommentBlock CmdLet As Add-On Into PowerShell ISE
Here are the steps that I have followed in order to have that Add-on in PowerShell ISE environment: ( You have all this already done if you have downloaded the zip file.)
- have created 09addons folder where my Modules are and for me, that was this location C:\Users\$env:USERNAME\[My] Documents\WindowsPowerShell\Modules
- have saved New-CommentBlock as PowerShell script (.ps1 file) in 09addons folder.
- have created and saved the PowerShell Script Module file (.psm1) in 09addons with the same name as the folder (09addons.psm1)
- have customized 09addons.psm1 module file with this line of code in order to load New-CommentBlock CmdLet into 09addons module
. $psScriptRoot\New-CommentBlock.ps1
- have customized Profile file ( Microsoft.PowerShellISE_profile.ps1) location for me: (C:\Users\$env:USERNAME\[My] Documents\WindowsPowerShell) with this line of code in order to Import 09addons Module
Import-Module 09addons
What Happens When You Start PowerShell ISE?
If you wonder why we have done all the steps in the previous section here is an explanation of PowerShell Workflow when every session starts
When you open Windows PowerShell ISE here are things that happen in the background even before we see the ISE window:
- New PowerShell session starts for the current user
- PowerShell profile files have been loaded into the session (one of them is Microsoft.PowerShellISE_profile.ps1 that we have just customized)
- The profile file will import modules. In our example, it will load the 09addons module among the others
- When the modules are imported the code inside the Script module file (.psm1) is executed. In our example, New-CommentBlock.ps1 script file will be executed
- When a script file is executed New-CommentBlock CmdLet function is loaded into the session. In our example this code will be executed:
New-CommentBlock -InstallMenu $true
… and that will add New-CommentBlock as Add-On Menu Item in Windows PowerShell ISE so we can use it as we need it. - Finally, our environment is customized and we see Windows PowerShell ISE application with Add-on New-CommentBlock added into our environment and we can start working on the environment
I hope this explains the previous steps.
How To Use New-CommentBlock CmdLet
We have several ways to exploit this fabulous CmdLet.
IMPORTANT: Put the cursor where you want to insert comment-based help with this CmdLet.
- We can press Ctrl + Alt + C and this will create a Comment-Based help template for us that we need to fill out and start writing our code.
- We can go to menu Add-ons and choose Insert comment block menu item in Windows PowerShell ISE and this will do the same thing as in the previous example (look the screenshot below)
Enjoy your PowerShell coding in a more efficient way!
Useful PowerShell Commands Related To Comment-Based Help
When we have finally written comment-based help for our Advance Function or CmdLet it would be nice to check it out the final result. So the best option to test our own comment-based help is to run Get-Help CmdLet against our own CmdLet with parameters and read the result. Like in the following examples:
Get-Help Get-Service
Get-Help Get-Service -Detailed
Get-Help Get-Service -Full
Get-Help Get-Service -Examples
Useful PowerShell Comment-Based Help Articles
Here are some useful articles and resources:
- About Comment Based Help
- Syntax of Comment-Based Help
- Comment-Based Help Keywords
- Placing Comment-Based Help in Functions
- Placing Comment-Based Help in Scripts
- Autogenerated Elements of Comment-Based Help
New-CommentBlock CmdLet Code
Here is the source code of the whole New-CommentBlock Add-on CmdLet. Enjoy!
<#
.SYNOPSIS
Inserts a full comment block
.DESCRIPTION
This function inserts a full comment block that is formatted the
way I format all my comment blocks.
.PARAMETER InstallMenu
Specifies if you want to install this as a PSIE add-on menu
.EXAMPLE
New-CommentBlock -InstallMenu $true
Description
-----------
Installs the function as a menu item.
.NOTES
FunctionName : New-CommentBlock
Created by : Jeff Patton
Date Coded : 09/13/2011 13:37:24
Modified by : Dejan Mladenovic
Date Modified : 02/09/2019 01:19:10
More info : http://improvescripting.com/
.LINK
How To Write PowerShell Function’s Or CmdLet’s Help (Fast)
https://gallery.technet.microsoft.com/scriptcenter/PSISELibraryps1-ec442972
#>
Function New-CommentBlock
{
[CmdletBinding()]
Param
(
$InstallMenu
)
Begin
{
$CommentBlock = @(
" <#`r`n"
" .SYNOPSIS`r`n"
" .DESCRIPTION`r`n"
" .PARAMETER`r`n"
" .EXAMPLE`r`n"
" .INPUTS`r`n"
" .OUTPUTS`r`n"
" .NOTES`r`n"
" FunctionName : `r`n"
" Created by : $($env:username)`r`n"
" Date Coded : $(Get-Date)`r`n"
" .LINK`r`n"
" http://improvescripting.com/`r`n"
" #>`r`n")
if ($InstallMenu)
{
Write-Verbose "Try to install the menu item, and error out if there's an issue."
try
{
$psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add("Insert comment block",{New-CommentBlock},"Ctrl+Alt+C") | Out-Null
}
catch
{
Return $Error[0].Exception
}
}
}
Process
{
if (!$InstallMenu)
{
Write-Verbose "Don't insert a comment if we're installing the menu"
try
{
Write-Verbose "Create a new comment block, return an error if there's an issue."
$psISE.CurrentFile.Editor.InsertText($CommentBlock)
}
catch
{
Return $Error[0].Exception
}
}
}
End
{
}
}
#region Execution examples
New-CommentBlock -InstallMenu $true
#endregion
Well done PowerShell Jedi you read the whole article!