In PowerShell single line comments start with a hash symbol, everything to the right of the # will be ignored.
# comment
In PowerShell 2.0 and above multi-line block comments can be used:
<# comment
contines
#>
Multi-line comments are typically used to add descriptive help at the start of a script, but also work to embed comment text within a command.
Comment-based Help was also added in PS 2.0, this allows the addition of some standardised tags to a scripts comments which allow the Script to interact with Get-Help.
See this template script, or read Help about_Comment_Based_Help for a full list of .Keywords.
Copy-Item demo.msi C:\install\demo.msi #copy the installer
<#
This script will talk to you in french
language function based on: www.example.com/powershell.html
Last updated: 1666-09-02
#>
Get-Content -Path <#configuration file#> C:\install\app64.ini
By using embedded comments you can document the arguments for a cmdlet:
PS C:\> Get-ChildItem <# list the items #> ` -Path $env:windir <# of the Windows system folder #> ` -Filter *.dll <# that are DLLs #> ` -Recurse <# and search all subfolders #>
Comment-based help topics can be added to functions and scripts. This is done using special help comment keywords that start with a period. Examples of these are below, you can add as many or as few of these to your script as needed to provide the relevant level of detailed help.
<# .SYNOPSIS This script/function does - What? .DESCRIPTION A more detailed description of why and how the function works. .PARAMETER DemoParam1 The parameter DemoParam1 is used to define the value of blah and also blah. .PARAMETER DemoParam2 The parameter DemoParam2 is used to define the value of blah and also blah. .EXAMPLE The example below does blah PS C:\> Example .EXAMPLE Another example .NOTES Author: Name Last Edit: yyyy-mm-dd Version 1.0 - initial release of blah Version 1.1 - update for blah #>
To display this help text, use Get-Help
e.g.
get-help ./script.ps1
get-help myfunction (this will only work once the function has been loaded/Dot sourced)Where to add the Comment-based help:
Comment-based help for a script must appear at the beginning of the script (it can also be placed at the end of the script file but only if the script is not signed.)
Comment-based help for a function can appear in one of 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.
Most people put all comments at the beginning of the script/function.
Default Help
If you call get-help for a script that does not have any comment based help but does have parameters defined with a PARAM ( ) statement, then get-help will return those parameter details.
It is also possible to get a slightly more verbose set of default help text by including just <# .SYNOPSIS #> at the top of the script.
See Help about_Comment_Based_Help for more.
Because PowerShell supports Tab Completion you need to be careful about copying and pasting Space + TAB characters (particularly just before the # comment delimiter).
Example:
Function demo() {
} # comment^ That line is }<space><tab> #
when copied/pasted onto the PowerShell command line, this happens:PS C:\batch> Function demo() {
>> } .\aaardvaark.cmd# comment
>>
The term '.\aaardvaark.cmd#' is not recognized as the name of a cmdlet, function, script file...
What is happening is that the space-tab gets expanded to match the first file in the current directory, in this case aaardvaark.cmd. If the sequence had been <space><tab><space> and the first file had been a PowerShell script or an executable then it would actually be run.If the white space consists of nothing but <space> characters (or nothing but <tab> characters) then this will never occur.
#Now stand in the place where you work, Now face West
Think about the place where you live, Wonder why you haven’t before# - REM 'Stand'
Escape characters - double \\ to escape them