about_Command_Syntax - PowerShell command help and examples

Describes the notation used for Windows PowerShell syntax in Help. (about_Command_Syntax)

 TOPIC
 
    about_Command_Syntax 

 SHORT DESCRIPTION
 
    Describes the notation used for Windows PowerShell syntax in Help. 

 LONG DESCRIPTION
 
    The Get-Help cmdlet displays the parameter usage for a cmdlet. The Get-Help 
    cmdlet uses the following special symbols: 

        Angle brackets (<>) indicate placeholder text. 
        Brackets ([]) indicate optional items. 
        Braces ({}) indicate a choice among values. 

    Some cmdlets have more than one set of parameters. Distinct parameter sets 
    can share some parameters. The Get-Help cmdlet displays all the parameter 
    sets for a cmdlet. 

    You can find additional information about a parameter in the parameter 
    description and in the parameter attribute table. To view complete 
    information about a parameter, use the Full or Parameter parameters of 
    Get-Help. 

  Syntax 
      Windows PowerShell cmdlet Help, Help topics, and other documentation use 
      the following notation for cmdlets in syntax descriptions. 

          <cmdlet name> -<Required Parameter name> <Required parameter Value> 
                       [-<Optional Parameter name> <Optional Parameter Value>] 
                       [-<Optional Switch Parameter>] 
                       [-<Optional Parameter Name>] <Required parameter Value> 

      The following is the syntax for the New-Alias cmdlet. 

          New-Alias [-Force] [-PassThru] [-Scope <string>] 
              [-Option {None | ReadOnly | Constant | Private | AllScope}] 
              [-Description <string>] [-Name] <string> [-Value] <string> 
              [-confirm] [-whatif] [<CommonParameters>] 

      The syntax is capitalized for readability, but Windows Powershell is 
      case-insensitive. 

      Parameters appear in order. The order of parameters is significant only 
      when the parameter names are optional. If you do not specify parameter 
      names when you use a cmdlet, Windows PowerShell assigns values to 
      parameters by position and by type. 

      Parameter names are preceded by a hyphen (-). Switch parameters appear 
      without a value type. Other parameters appear with the Microsoft .NET 
      Framework type of the argument required or with an enumeration of 
      possible values. For more information about .NET Framework types, 
      see http://go.microsoft.com/fwlink/?LinkId=143682. 

      Angle brackets (<>) indicate placeholder text. This text can describe the 
      type of an item (such as a string or a Process object). It can also be a 
      placeholder for one or more common parameters. 

      Brackets ([]) indicate optional items. A parameter can be optional, or 
      the name of a required parameter can be optional. Switch parameters are 
      always optional. 

      Braces ({}) appear around the values of an enumeration. In the example of 
      the New-Alias cmdlet, the Option parameter can have any of the listed 
      values. 

  Optional Items 
      Brackets ([]) surround optional items. For example, in the New-Alias 
      cmdlet syntax description, the Scope parameter is optional. This is 
      indicated in the syntax by the brackets around the parameter name 
      and type: 

          [-Scope <string>] 

      Both the following examples are correct uses of the New-Alias cmdlet: 

          New-Alias -Name utd -Value Update-TypeData 
          New-Alias -Name utd -Value Update-TypeData -Scope global 

      A parameter name can be optional even if the value for that parameter is 
      required. This is indicated in the syntax by the brackets around the 
      parameter name but not the parameter type, as in this example from the 
      New-Alias cmdlet: 

          [-Name] <string> [-Value] <string> 

      The following  commands correctly use the New-Alias cmdlet. The commands 
      produce the same result: 

          New-Alias -Name utd -Value Update-TypeData 
          New-Alias -Name utd Update-TypeData 
          New-Alias utd -Value Update-TypeData 
          New-Alias utd Update-TypeData 

      If the parameter name is not included in the statement as typed, Windows 
      PowerShell tries to use the position of the arguments to assign the 
      values to parameters. 

      The following example is not complete: 

          New-Alias utd 

      This cmdlet requires values for both the Name and Value parameters. 

      In syntax examples, brackets are also used in naming and casting to 
      .NET Framework types. In this context, brackets do not indicate an 
      element is optional. 

  Array Arguments 
      Brackets are also used in syntax descriptions to represent an array. 
      The following example shows the syntax for the Restart-Service cmdlet: 

          Restart-Service [-Name] <string[]> [-Include <string[]>] 
              [-Exclude <string[]>] [-Force] [-PassThru] [-Confirm] [-WhatIf] 
              [<CommonParameters>] 

      The Name parameter requires an argument. Specifically, it requires the 
      name of the service to be restarted. It can take a comma-separated list 
      of services, as in the following example: 

          Restart-Service RasAuto, RasMan, RemoteAccess 

SEE ALSO 
    Get-Help 

C:\Windows>powershell get-help about_Comment_Based_Help -full 

Microsoft Windows [Version 10.0.19045.3693]
Copyright (c) 2023 Microsoft Corporation.

ColorConsole [Version 3.7.1000] PowerShell 2.0-Export

Windows 11, 10, 8.1, 8, 7 / Server 2022, 2019, 2016