Как получить справочные сообщения для параметров моего скрипта Powershell?

Question

У меня есть сценарий powershell (setup.ps1), который мы используем в качестве точки входа для наших сценариев установки среды разработки.Он принимает параметр:

param(
    [Parameter(Position=0,HelpMessage="The targets to run.")]
    [Alias("t")]
    [string[]]
    $Targets = "Help"
)

Когда я запускаю

PS > get-help .\setup.ps1 -detailed

в разделе параметров, мое справочное сообщение не появляется:

PARAMETERS
    -Targets <String[]>

Что делатьМне нужно сделать, чтобы мои сообщения о параметрах отображались?

Answer 1

Вы помещаете определенный стиль комментария вверху файла, который может быть декодирован справочной системой PowerShell. Вот пример:

<#
.SYNOPSIS
    .
.DESCRIPTION
    .
.PARAMETER Path
    The path to the .
.PARAMETER LiteralPath
    Specifies a path to one or more locations. Unlike Path, the value of 
    LiteralPath is used exactly as it is typed. No characters are interpreted 
    as wildcards. If the path includes escape characters, enclose it in single
    quotation marks. Single quotation marks tell Windows PowerShell not to 
    interpret any characters as escape sequences.
.EXAMPLE
    C:\PS> 
    <Description of example>
.NOTES
    Author: Keith Hill
    Date:   June 28, 2010    
#>
function AdvFuncToProcessPaths
{
    [CmdletBinding(DefaultParameterSetName="Path")]
    param(
        [Parameter(Mandatory=$true, Position=0, ParameterSetName="Path", 
                   ValueFromPipeline=$true, 
                   ValueFromPipelineByPropertyName=$true,
                   HelpMessage="Path to ...")]
        [ValidateNotNullOrEmpty()]
        [string[]]
        $Path,

        [Alias("PSPath")]
        [Parameter(Mandatory=$true, Position=0, ParameterSetName="LiteralPath", 
                   ValueFromPipelineByPropertyName=$true,
                   HelpMessage="Path to ...")]
        [ValidateNotNullOrEmpty()]
        [string[]]
        $LiteralPath
    )
    ...

Для получения дополнительной информации см. Раздел справки - man about_comment_based_help.

Answer 2

Очевидно, что если у вас определен заголовок справки, вы можете просто использовать примечание (#) за параметром (в этом примере: # Цели для запуска. ):

<#
.SYNOPSIS
    .
.DESCRIPTION
    .
.PARAMETER Path
    The path to the .
.PARAMETER LiteralPath
    Specifies a path to one or more locations. Unlike Path, the value of 
    LiteralPath is used exactly as it is typed. No characters are interpreted 
    as wildcards. If the path includes escape characters, enclose it in single
    quotation marks. Single quotation marks tell Windows PowerShell not to 
    interpret any characters as escape sequences.
#>

Param(
    [String]$Targets = "Help"   #The targets to run.
)

Результат:

PS C:\> Get-help .\Setup.ps1 -Detailed

NAME
    C:\Setup.ps1

SYNOPSIS
    .


SYNTAX
    C:\Setup.ps1 [[-Targets] <String>] [<CommonParameters>]


DESCRIPTION
    .


PARAMETERS
    -Targets <String>
        The targets to run.

Answer 3

one просто нужна <# .SYNOPSIS #> часть поверх файла, чтобы он заработал, и вы можете комментировать свои параметры, аккуратно встроенные :

<# .SYNOPSIS #>
param(
   [String]$foo   ## my 1st cool param
  ,[Switch]$bar  ## my 2nd crazy switch
)
...

(проверено с PS 5.1.14409.1018)