Как определить документацию по пользовательской команде (используя Get-Command или Get-Help)

Question

Допустим, у меня есть пользовательская команда:

function Search-ForStringInFile($string)
{
        ls -Recurse | Select-String -Pattern "$string" -List | Select Path
}

И я хочу иметь возможность запустить Get-Help Search-ForStringInFile или Get-Command Search-ForStringInFile, чтобы получить описание того, что команда делает.

Описание: Поиск по ключевому слову во всех файлах в / в текущем каталоге

Есть ли специальный синтаксис комментариев, который я могу использовать в function для добавления этой документации?

Answer 1

Это называется справкой на основе комментариев.PowerShell ISE имеет действительно отличный фрагмент кода для того, чтобы делать именно то, что вы хотите.Просто нажмите Control + J и выберите «Командлет - Расширенные функции», чтобы загрузить фрагмент, который я предоставлю ниже:

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
#>
function Verb-Noun
{
}

Как только вы заполните значения для каждого из них выше ( см. Документы здесь для всех доступных полей) и нажмите F5, справка появится в вашей функции.

PS>Get-Help Verb-Noun
NAME
    Verb-Noun

SYNOPSIS
    Short description


SYNTAX
    Verb-Noun [-Param1] <Object> [-Param2 <Int32>] [-WhatIf] [-Confirm] [<CommonParameters>]

    Verb-Noun [-Param3 <String>] [-WhatIf] [-Confirm] [<CommonParameters>]


DESCRIPTION
    Long description


PARAMETERS
    -Param1 <Object>
        Param1 help description

        Required?                    true
        Position?                    1
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)
        Accept wildcard characters?  false

    -Param2 <Int32>
        Param2 help description

        Required?                    false
        Position?                    named
        Default value                0
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Param3 <String>
        Param3 help description

        Required?                    false
        Position?                    named
        Default value                
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -WhatIf [<SwitchParameter>]

        Required?                    false
        Position?                    named
        Default value                
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Confirm [<SwitchParameter>]

        Required?                    false
        Position?                    named
        Default value                
        Accept pipeline input?       false
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see 
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). 

INPUTS
    Inputs to this cmdlet (if any)


OUTPUTS
    Output from this cmdlet (if any)


NOTES


        General notes

    -------------------------- EXAMPLE 1 --------------------------

    PS C:\>Example of how to use this cmdlet






    -------------------------- EXAMPLE 2 --------------------------

    PS C:\>Another example of how to use this cmdlet







RELATED LINKS

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

• До объявления функции
• После объявления функции (ewww)
• В конце вашей функции (небыть опровергнутым, но морально неправильно выбирать этот вариант).

В документах приведены примеры каждого из утвержденных мест здесь .