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 the Get-Help  command includes the -Component  parameter of Get-Help .
• .Role – The user role for the help topic. This content appears when the Get-Help  command includes the -Role  parameter of Get-Help .
• .Functionality – The intended use of the function. This content appears when the Get-Help  command includes the -Functionality  parameter of Get-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 the Export-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 of Get-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
.LINK
PowerShell 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”]

Summary

Article Name

PowerShell Comment Based Help

Description

PowerShell Comment Based Help. In this tutorial you will find information about PowerShell Comment Based Help and its use. Stephanos Constantinou Blog

Author

Stephanos

Publisher Name

Stephanos Constantinou Blog

Publisher Logo