PowerShell Comment Based Help
In this tutorial we will see about PowerShell Comment Based Help. Help information help us and others, that we will distribute our scripts or functions. you can contain a lot in information in the help section.We are able to provide help on functions and scripts.
The help information can be displayed by using Get-Help
cmdlet. There are two ways to provide help for functions and scripts. We are able to provide help either comment based or XML files. The format of comment based help is displayed, is the same as the help topics that are generated from XML files.
Users can use all of the parameters of Get-Help
, such as Detailed, Full, Examples, and Online, to display the contents of comment-based help. In order to use XML files based help you need to use .ExternalHelp
keyword. In this post we will see only the comment based help. Let’s see few details about it.
[adinserter name=”In Article”]
Comment Based Help Syntax
Comment based help has a specific syntax.
Code:
#.<help keyword> #<help content>
or
<# .<help keyword> <help content> #>
Comment based help must be a series of comments. You need to either use #
at the beginning of each line or use <#
and #>
symbols for a comment block. Comment based help has different sections. The sections are defined by specific keywords, which are followed by the content of the specific keyword.
A comment block must contain at least one help keyword. Some of the keywords, such as .EXAMPLE
, can appear many times in the same comment block. The Help content for each keyword begins on the line after the keyword and can span multiple lines. All of the lines in a comment-based Help topic must be contiguous.
If a comment-based Help topic follows a comment that is not part of the Help topic, there must be at least one blank line between the last non-Help comment line and the beginning of the comment-based Help.
[adinserter name=”In Article”]
Comment Based Help Keywords
Following are the valid comment based help keywords. Below is the typical order that they appear in a help topic. Keywords are not case-sensitive and they can appear in any order in the comment based help. The description of each keyword is provided by Microsoft.
.Synopsis
– A brief description of the function or script. This keyword can be used only once in each topic..Description
– A detailed description of the function or script. This keyword can be used only once in each topic..Parameter
<Parameter Name> – The description of a parameter. You can include a.Parameter
keyword for each parameter in the function or script..Example
– A sample command that uses the function or script, optionally followed by sample output and a description. Repeat this keyword for each example..Inputs
– The Microsoft .NET Framework types of objects that can be piped to the function or script. You can also include a description of the input objects..Outputs
– The .NET Framework type of the objects that the cmdlet returns. You can also include a description of the returned objects..Notes
– Additional information about the function or script..Link
– The name of a related topic. Repeat this keyword for each related topic. This content appears in the Related Links section of the Help topic..Component
– The technology or feature that the function or script uses, or to which it is related. This content appears when theGet-Help
command includes the-Component
parameter ofGet-Help
..Role
– The user role for the help topic. This content appears when theGet-Help
command includes the-Role
parameter ofGet-Help
..Functionality
– The intended use of the function. This content appears when theGet-Help
command includes the-Functionality
parameter ofGet-Help
..ForwardHelpTargetName <Command Name>
– Redirects to the Help topic for the specified command. You can redirect users to any Help topic, including Help topics for a function, script, cmdlet, or provider..ForwardHelpCategory <Category>
– Specifies the Help category of the item in ForwardHelpTargetName. Valid values are Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter, or All. Use this keyword to avoid conflicts when there are commands with the same name..RemoteHelpRunspace <PSSession-Variable>
– Specifies a session that contains the help topic. Enter a variable that contains a PSSession. This keyword is used by theExport-PSSession
cmdlet to find the help topics for the exported commands..ExternalHelp <XML Help File>
– Specifies the path and/or name of an XML-based Help file for the script or function.
Parameter Keyword
The .Parameter
keywords can appear in any order in the comment block, but the order in which the parameters appear in the Param
statement or function declaration determines the order in which the parameters appear in help topic. If you want to change the order of parameters in the help topic, you need change the order of the parameters in the Param
statement or function declaration. You can also specify a parameter description by placing a comment in the Param
statement immediately before the parameter variable name. If you use both a Param
statement comment and a .Parameter
keyword, the description associated with the .Parameter
keyword is used, and the Param
statement comment is ignored.
Link Keyword
The .Link
keyword content can also include a Uniform Resource Identifier (URI) to an online version of the same help topic. The online version opens when you use the Online
parameter of Get-Help
. The URI must begin with “http” or “https”.
ExternalHelp Keyword
The .ExternalHelp
keyword tells the Get-Help
cmdlet to get help for the script or function in an XML-based file. The .ExternalHelp
keyword is required when using an XML-based help file for a script or function. Without it, Get-Help
will not find a help file for the function or script. The .ExternalHelp
keyword takes precedence over all other comment based help keywords. When .ExternalHelp
is present, the Get-Help
cmdlet does not display comment based help, even when it cannot find a help file that matches the value of the keyword.
When the function is exported by a script module, the value of .ExternalHelp
should be a file name without a path. Get-Help
looks for the file in a locale-specific subdirectory of the module directory. There are no requirements for the file name, but a best practice is to use the following file name format: <ScriptModule>.psm1-help.xml
.
When the function is not associated with a module, include a path and file name in the value of the .ExternalHelp
keyword. If the specified path to the XML file contains UI-culture-specific subdirectories, Get-Help
searches the subdirectories recursively for an XML file with the name of the script or function in accordance with the language fallback standards established for Windows, just as it does for all XML-based Help topics.
[adinserter name=”In Article”]
Comment Based Help in Functions
There are specific locations in the function that you are able to place the help information in order for the Get-Help
cmdlet recognize the help information.
Function comment based help locations:
- At the beginning of the function body.
function MyFunction { <# .Synopsis MyFunction Synopsis .Description MyFunction Description #> MyFuction code }
- At the end of the function body.
function MyFunction { MyFuction code <# .Synopsis MyFunction Synopsis .Description MyFunction Description #> }
- Before the Function keyword. When the function is in a script or script module, there cannot be more than one blank line between the last line of the comment-based help and the Function keyword. Otherwise,
Get-Help
associates the help with the script, not with the function.
<# .Synopsis MyFunction Synopsis .Description MyFunction Description #> function MyFunction { MyFuction code }
[adinserter name=”In Article”]
Comment Based Help in Scripts
There are specific locations in the scripts that you are able to place the help information in order for the Get-Help
cmdlet recognize the help information.
Script comment based help locations:
- At the beginning of the script file. Script Help can be preceded in the script only by comments and blank lines.
<# .Synopsis Synopsis of script .Description Description of script #> param [string]$Name ...
- At the end of the script file.
... param [string]$Name function MyFunction {code} <# .Synopsis Synopsis of script .Description Description of script #>
If the first item in the script body (after the Help) is a function declaration, there must be at least two blank lines between the end of the script Help and the function declaration. Otherwise, the Help is interpreted as being Help for the function, not Help for the script.
[adinserter name=”In Article”]
Aggregated Elements
The Get-Help
cmdlet automatically generates several elements of a comment-based topic. These autogenerated elements make comment-based help look very much like the help that is generated from XML files. You cannot edit these elements directly, but in many cases you can change the results by changing the source of the element.
The Get-Help
cmdlet automatically generates the following elements of a help topic:
- Name – The Name section of a function Help topic is taken from the function name in the function definition. The Name of a script Help topic is taken from the script file name. To change the name or its capitalization, change the function definition or the script file name.
- Syntax – The Syntax section of the Help topic is generated from the parameter list in the Param statement of the function or script. To add detail to the Help topic syntax, such as the .NET Framework type of a parameter, add the detail to the parameter list. If you do not specify a parameter type, the “Object” type is inserted as the default value.
- Parameter List – The Parameters section of the Help topic is generated from the parameter list in the function or script and from the descriptions that you add by using the
.Parameters
keyword or comments in the parameter list. - Common Parameters – The common parameters are added to the syntax and parameter list of the Help topic, even if they have no effect.
- Parameter Attribute Table –
Get-Help
generates the table of parameter attributes that appears when you use the Full or Parameter parameter ofGet-Help
. The value of the Required, Position, and Default value attributes is taken from the function or script syntax. - Remarks – The Remarks section of the Help topic is automatically generated from the function or script name. You cannot change or affect its content.
[adinserter name=”In Article”]
Example of Help
Code:
function Get-PasswordNumber { <# .SYNOPSIS Calculates the number of possible passwords .DESCRIPTION Calculates the number of possible passwords based on the input so you will know the actual number before you proceed to create your dictionary file. .PARAMETER CharacterSet Specifies the characters (letters, numbers, symbols) that need to be included. Parameter is mandatory. .PARAMETER MinCharacters Specifies the minimum characters of the generated passwords. Parameter is mandatory. .PARAMETER MaxCharacters Specifies the maximum characters of the generated passwords. Parameter is mandatory. .PARAMETER IncludeCapital Specifies whether or not to include upper case letters along with the lower case letters. .PARAMETER CapitalOnly Specifies whether or not all lower case letters to be converted to upper case letters. .INPUTS System.String. Get-PasswordNumber can accept a string value to determine the CharacterSet parameter. .OUTPUTS System.Double. Get-PasswordNumber returns the number of passwords that can be created. .EXAMPLE C:\PS> Get-PasswordNumber -CharacterSet "a,b,c,1,2,3,$,*,&" -MinCharacters 2 -MaxCharacters 5 66420 .EXAMPLE C:\PS> Get-PasswordNumber -Characters "a,b,c,1,2,3,$,*,&" -MinCharacters 2 -MaxCharacters 5 -IncludeCapital 271440 .EXAMPLE C:\PS> Get-PasswordNumber -Characters "a,b,c,1,2,3,$,*,&" -MinCharacters 2 -MaxCharacters 5 -CapitalOnly 66420 .EXAMPLE C:\PS> Get-PasswordNumber -Characters alphabet -MinCharacters 2 -MaxCharacters 5 12356604 .LINKPowerShell Module DictionaryFile#> [cmdletbinding()] param( [parameter(Mandatory = $true,ValueFromPipeline = $true)][String]$CharacterSet, [parameter(Mandatory = $true)][Uint32]$MinCharacters, [parameter(Mandatory = $true)][Uint32]$MaxCharacters, [switch]$IncludeCapital, [switch]$CapitalOnly) ... }
Output:
I hope the tutorial about PowerShell Comment Based Help is helpful.
Please let me know your comments and thoughts.
You feedback is appreciated.
[adinserter name=”In Article”]
Related Links
- PowerShell Tutorials
- PowerShell Scripts
- about_Comment_Based_Help | Microsoft Docs
- Syntax of Comment-Based Help | Microsoft Docs
- Comment-Based Help Keywords | Microsoft Docs
- Placing Comment-Based Help in Functions | Microsoft Docs
- Placing Comment-Based Help in Scripts | Microsoft Docs
- Autogenerated Elements of Comment-Based Help | Microsoft Docs
- Examples of Comment-Based Help | Microsoft Docs
- Get-Help – Microsoft Docs
- PowerShell Comments
[adinserter name=”Matched-Content”]


Leave a Reply