PowerShell Language

From DataSelf Knowledge Base
Jump to navigation Jump to search

Comment-based help

The Powershell shell knows to look for specially formatted comments inside of a script or function, and it parses those comments to construct the same type of help display you’d see with a native cmdlet.

  • The help data can be used inside a function body or in a script.
  • In order for the help comments to be parsed, they must be the FIRST comments in the function or script.
  • Comment-based help for a function can appear in one of three locations:
  1. -- At the beginning of the function body.
  2. -- At the end of the function body.
  3. -- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword.


 function foo
    Counts the Grateful Dead shows in my archives
    System.String. Add-Extension returns a string with the extension or file name.
 Return "somestring"

Main Key Words

  • .SYNOPSIS –a brief explanation of what the script or function does.
  • .DESCRIPTION – a more detailed explanation of what the script or function does.
  • .PARAMETER name – an explanation of a specific parameter. Replace name with the parameter name. You can have one of these sections for each parameter the script or function uses.
    • Type the parameter name on the same line as the .PARAMETER keyword.
      • Type the parameter description on the lines following the .PARAMETER keyword.
  • .EXAMPLE – an example of how to use the script or function. You can have multiple .EXAMPLE sections if you want to provide more than one example.
  • .NOTES – any miscellaneous notes on using the script or function.
  • .LINK – a cross-reference to another help topic; you can have more than one of these. If you include a URL beginning with http:// or https://, the shell will open that URL when the Help command’s –online parameter is used.
  • .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.
  • .FUNCTIONALITY - The intended use of the function. This content appears when the Get-Help command includes the Functionality parameter of Get-Help.