Like any other programming language, PowerShell also supports comments. In this article, we will look into How to use Comments in PowerShell Script and also How to add comment-based help topics for Functions and Scripts in details.
Single Line Comment in PowerShell
If you would like to use Single Line comment in Powershell script or in the code block you can use it with a special character “#“. Single line comments are supported by all the PowerShell versions. You could use Single Line comments as PowerShell inline comments.
Example of Single Line Comment in PowerShell Code
# This is a single line comment and below command returns date get-date
MultiLine Comments in PowerShell
Multiline comments are used to add descriptive text in the PowerShell code. Anything which is added in between <# Multiline comment goes here #> is considered as multi-line block comments. You could also use this feature as PowerShell comment block to comment multiple lines of code.
Version Support – MultiLine Comments are supported in PowerShell version 2.0 and above. Hence if you are using PowerShell V1.o then you can use only single line comments.
Example of MultiLine Comments in PowerShell
<# -------------------------------------- Multi-line comment in PowerShell V2+ -------------------------------------- The below command will return the Current operating System Version Last updated: 1/1/2016 #> [environment]::OSVersion.Version
PowerShell also supports Advanced commenting also called as about_Comment_Based_Help. Using this you could write the help topics for the functions and scripts.
Syntax for Comment Based Help in Functions
Comment based help text can appear in one of the three places in the PowerShell function.
- Beginning of the function body
- End of the function body
- Before the function keyword. There should not be more than 1 line break between the help text and the function keyword.
Example of Comment Based Help in Functions
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
.PARAMETER Name
Specifies the file name.
.PARAMETER Extension
Specifies the extension. "Txt" is the default.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
http://www.code.askmein.com/
.LINK
Set-Item
#>
}
In Order to get the help text for the above function, all you need to do is run below command and you will get complete help description for the function.
get-help add-extension -full
Syntax for Comment-Based Help in Scripts
If you are using the PowerShell script then the Comment-based help can appear in one of the three locations.
- At the beginning of the Script File.
- At the end of the Script. If the script is signed then place the comment-based help text in the beginning of the script file . The end of the script file is occupied by the signature block.
Note: If the first item in the Script body is a function then leave two blank line and place the comment-based help text else the help text will be interpreted as the help text for the function, not for the Script.
<#
.< help keyword>
< help content>
Leave 2 blank lines after the comment close
#>
function Get-Function { }
As shown in the Powershell Comment-Based Help text in functions here also you can add various things like Synopsis, Description, Function Params etc.
In Order to get the help text for the PowerShell script files you need to run the command as shown below. You will get complete help description for the script file.
get-help .\filename.ps1 -full
Replace the filename with your PowerShell Script filename and execute the command to get the complete help text.
Srinivas Ramakrishna
