Поделиться через


about_Comment_Based_Help

Назначение: Windows PowerShell 2.0, Windows PowerShell 3.0

Вставьте сюда введение.

РАЗДЕЛ

about_Comment_Based_Help

КРАТКОЕ ОПИСАНИЕ

В этом разделе объясняется, как писать разделы справки на основе комментариев для функций и сценариев.

ПОДРОБНОЕ ОПИСАНИЕ

Разделы справки на основе комментариев по функциям и сценариям можно писать с помощью специальных ключевых слов комментария справки.

Командлет Get-Help отображает справку на основе комментариев в том же формате, в каком он выводит разделы справки по командлетам, созданные на основе XML-файлов. Чтобы отобразить содержимое справки на основе комментариев, пользователи могут использовать все параметры Get-Help, такие как Detailed, Full, Example и Online.

Можно также писать файлы справки на основе XML по функциям и сценариям. Чтобы командлет Get-Help мог найти файл справки на основе XML по функции или сценарию, используйте ключевое слово ExternalHelp. Без этого ключевого слова Get-Help не сможет найти разделы справки на основе XML по функциям или сценариям.

В этом разделе объясняется, как писать разделы справки по функциям и сценариям. Сведения о способах отображения разделов справки по функциям и сценариям см. в разделе Get-Help.

ПРИМЕЧАНИЕ.

Командлеты Update-Help и Save-Help работают только с XML-файлами. Обновляемая справка не поддерживает разделы справки на основе комментариев.

ЗАМЕЧАНИЕ ПО УСТРАНЕНИЮ НЕПОЛАДОК.

Значения по умолчанию и значение параметра "Принимать подстановочные знаки" не отображаются в таблице атрибутов параметров, даже если они определены в функции или сценарии. Чтобы помочь пользователям, включите эти сведения в описание параметра.

СИНТАКСИС СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ

Синтаксис справки на основе комментариев выглядит следующим образом:

        # .< help keyword>
        # <help content>
 
    -or -

        <#
            .< help keyword>
            < help content>
        #>

Справка на основе комментариев пишется как серия комментариев. Можно ввести символ комментария (#) перед каждой строкой комментариев или использовать символы "<#" и "#>", чтобы создать блок комментариев. Все строки в блоке комментариев интерпретируются как комментарии.

Все строки в разделе справки на основе комментариев должны быть сплошными. Если раздел справки на основе комментариев следует за комментарием, который не является частью раздела справки, должна быть как минимум одна пустая строка между последней строкой несправочного комментария и началом справки на основе комментариев.

Каждый раздел справки на основе комментариев определяется ключевыми словами. Перед каждым ключевым словом справки на основе комментариев ставится точка (.). Ключевые слова могут располагаться в любом порядке. В именах ключевых слов регистр не учитывается.

Например, ключевое слово Description предшествует описанию функции или сценария.

        <#
    .Description
            Get-Function displays the name and syntax of all functions in the session.
        #>

Блок комментариев должен содержать хотя бы одно ключевое слово. Некоторые ключевые слова, например EXAMPLE, могут многократно использоваться в одном блоке комментариев. Содержание справки по каждому ключевому слову начинается в строке после ключевого слова и может занимать несколько строк.

СИНТАКСИС СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ В ФУНКЦИЯХ

Справка по функции на основе комментариев может отображаться в одном из трех мест:

        -- 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.

Например:

        function Get-Function 
        {
            <#
            .< help keyword>
            < help content>
            #>

            <function commands>
        }


    -or -

        function Get-Function 
        {
            <function commands>

            <#
            .< help keyword>
            < help content>
            #>
        }

    -or -

        <#
        .< help keyword>
        < help content>
        #>
        function Get-Function { }

СИНТАКСИС СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ В СЦЕНАРИЯХ

Справка на основе комментариев по сценарию может отображаться в одном из следующих двух мест в сценарии:

     -- At the beginning of the script file. Script help can be preceded in the
       script only by comments and blank lines.


     -- If the first item in the script body (after the help) is a function
       declaration, there must be at least two blank lines between the end of the
       script help and the function declaration. Otherwise, the help is
       interpreted as being help for the function, not help for the script.


    -- At the end of the script file. However, if the script is signed, place
       Comment-based help at the beginning of the script file. The end of the 
       script is occupied by the signature block.

Например:

        <#
        .< help keyword>
        < help content>
        #>


        function Get-Function { }

    -or-


        function Get-Function { }

        <#
        .< help keyword>
        < help content>
        #>

СИНТАКСИС СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ В МОДУЛЯХ СЦЕНАРИЕВ

В модуле сценариев (.psm1) справка на основе комментариев использует синтаксис функций, а не сценариев. С помощью синтаксиса сценариев невозможно написать справку по всем функциям, определенным в модуле сценариев.

Например, если вы используете ключевое слово ExternalHelp, чтобы определить файлы справки на основе XML по функциям в модуле сценария, необходимо добавить комментарий ExternalHelp в каждую функцию.

    # .ExternalHelp <XML-file-name>
    function <function-name>
    {
        ...
    }

КЛЮЧЕВЫЕ СЛОВА СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ

Ниже приведены допустимые ключевые слова справки на основе комментариев. Они перечислены в порядке, в котором обычно представлены в разделе справки, вместе с описанием. Эти ключевые слова могут располагаться в любом порядке в справке на основе комментариев, и регистр в них не учитывается.

.SYNOPSIS

Краткое описание функции или сценария. Это ключевое слово может использоваться в каждом разделе только один раз.

.DESCRIPTION

Подробное описание функции или сценария. Это ключевое слово может использоваться в каждом разделе только один раз.

.PARAMETER <Parameter-Name>

Описание параметра. Ключевое слово .PARAMETER добавляется к каждому параметру в синтаксисе функции или сценария.

Имя параметра вводится в одной строке с ключевым словом .PARAMETER. Описание параметра вводится в строках после ключевого слова .PARAMETER. Windows PowerShell интерпретирует весь текст между строкой .PARAMETER и следующим ключевым словом или концом блока комментариев как часть описания параметра. Описание может содержать разрывы абзацев.

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

Кроме того, можно указать описание параметра, поместив комментарий в синтаксисе функции или сценария непосредственно перед именем переменной параметра. Если вы одновременно используете комментарий синтаксиса и ключевое слово Parameter, применяется связанное с этим словом описание, а комментарий синтаксиса игнорируется.

.EXAMPLE

Пример команды, использующий функцию или сценарий. При необходимости за ним следует пример выходных данных и описание. Это ключевое слово необходимо повторить для каждого примера.

.INPUTS

Объекты типа Microsoft .NET Framework, которые можно передать в функцию или сценарий по конвейеру. Кроме того, можно включить описание входных объектов.

.OUTPUTS

Объекты типа .NET Framework, возвращаемые командлетом. Кроме того, можно включить описание возвращаемых объектов.

.NOTES

Дополнительные сведения о функции или сценарии.

Название связанного раздела. Значение отображается в строке под ключевым словом .LINE и должно следовать за символом комментария (#) или быть включено в блок комментариев.

Ключевое слово .LINK необходимо повторить для каждого связанного раздела.

Это содержимое отображается в разделе справки со ссылками по теме (Related Links).

Ключевое слово Link может также включать универсальный код ресурса (URI) для сетевой версии того же раздела справки. Сетевая версия открывается при использовании параметра Online командлета Get-Help. URI должен начинаться с http или https.

.COMPONENT

Технология или компонент, которые используются функцией или сценарием или связаны с ними. Это содержимое отображается, если команда Get-Help включает параметр Component.

.ROLE

Роль пользователя для раздела справки. Это содержимое отображается, если команда Get-Help включает параметр Role.

.FUNCTIONALITY

Назначение функции. Это содержимое отображается, если команда Get-Help включает параметр Functionality.

.FORWARDHELPTARGETNAME <Command-Name>

Перенаправляет пользователей к разделу справки по указанной команде. Можно перенаправлять пользователей к любому разделу справки, включая разделы справки по функциям, сценариям, командлетам или поставщикам.

.FORWARDHELPCATEGORY <Category>

Определяет категорию справки элемента в ключевом слове ForwardHelpTargetName. Допустимые значения: Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter и All. Это ключевое слово позволяет избежать конфликтов при наличии команд с одинаковым именем.

.REMOTEHELPRUNSPACE <PSSession-variable>

Определяет сеанс, который содержит раздел справки. Необходимо ввести переменную, содержащую PSSession. С помощью этого ключевого слова командлет Export-PSSession находит разделы справки по экспортированным командам.

.EXTERNALHELP <XML Help File>

Определяет файл справки на основе XML по сценарию или функции.

Если функция или сценарий записаны в XML-файлах, требуется ключевое слово ExternalHelp. Без этого ключевого слова командлет Get-Help не сможет найти файл справки на основе XML по функции или сценарию.

Ключевое слово ExternalHelp имеет приоритет над другими ключевыми словами справки на основе комментариев. С ключевым словом ExternalHelp командлет Get-Help не отображает справку на основе комментариев, даже если он не может найти раздел справки, соответствующий значению ключевого слова ExternalHelp.

Если функция экспортируется модулем, задайте значение ключевого слова ExternalHelp для имени файла без пути. Командлет Get-Help выполняет поиск указанного имени файла во вложенной папке каталога модуля, соответствующей выбранному языку. Специальных требований к имени файла справки на основе XML по функции нет, но рекомендуется использовать следующий формат:

        <ScriptModule.psm1>-help.xml

Если функция не включена в модуль, в файл справки на основе XML следует добавить путь. Если значение включает путь, а путь содержит подкаталоги, соответствующие выбранным региональным параметрам пользовательского интерфейса, командлет Get-Help выполняет в подкаталогах рекурсивный поиск XML-файла с именем сценария или функции в соответствии с базовыми языковыми параметрами, установленными для Windows, аналогично тому, как это делается в каталоге модуля.

Подробнее о формате файлов справки на основе XML по командлетам можно узнать в статье библиотеки MSDN "Создание справки по командлетам" по адресу https://go.microsoft.com/fwlink/?LinkID=123415.

АВТОМАТИЧЕСКИ СОЗДАВАЕМОЕ СОДЕРЖИМОЕ

Имя, синтаксис, список параметров, таблица атрибутов параметров, общие параметры и замечания автоматически создаются с помощью командлета Get-Help.

Имя.

Узел Name раздела справки по функции создается на основе имени функции в ее синтаксисе. Имя раздела справки по сценарию создается на основе имени файла сценария. Чтобы изменить имя или регистр букв, измените синтаксис функции или имя файла сценария.

Синтаксис:

Узел Syntax раздела справки создается на основе синтаксиса функции или сценария. Чтобы добавить данные в синтаксис раздела справки, например параметр типа .NET Framework, добавьте данные в синтаксис функции или сценария. Если тип параметра не указан, в качестве значения по умолчанию добавляется тип Object.

Список параметров:

Список параметров в разделе справки создается на основе синтаксиса функции или сценария, а также описаний, добавляемых с помощью ключевого слова Parameters. Параметры функции отображаются в узле Parameters раздела справки в том же порядке, в каком они отображаются в синтаксисе функции или сценария. Написание и регистр букв имен параметров также берутся из синтаксиса и не зависят от имени параметра, указанного с помощью ключевого слова Parameter.

Общие параметры:

Общие параметры добавляются в синтаксис и список параметров раздела справки, даже если они недействительны. Подробнее об общих параметрах можно узнать в статье about_CommonParameters.

Таблица атрибутов параметров:

Командлет Get-Help создает таблицу атрибутов параметров, которая отображается при использовании параметра Full или Parameter командлета Get-help. Значения атрибутов Required, Position и Default берутся из синтаксиса функции или сценария.

ЗАМЕЧАНИЕ ПО УСТРАНЕНИЮ НЕПОЛАДОК.

Значения по умолчанию не отображаются в таблице атрибутов параметров, даже если они определены в функции или сценарии. Чтобы помочь пользователям, включите список значений по умолчанию в описание параметра.

Замечания:

Узел Remarks (Замечания) раздела справки автоматически создается на основе имени функции или сценария. Изменить его содержимое невозможно.

ОТКЛЮЧЕНИЕ СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ

[Эта технология была предложена Ричем Прескоттом (Rich Prescott), инженером Windows из Нью-Йорка, США.]

Справку на основе комментариев можно отключить. В результате справка на основе комментариев становится неактивной, но не удаляется.

Чтобы отключить справку на основе комментариев, заключите комментарии в here-строку. Чтобы скрыть here-строку, присвойте ее переменной или передайте по конвейеру в командлет Out-Null.

При отключении справка на основе комментариев теряет свое действие.

Например, следующая функция содержит справку на основе комментариев:

            <#
            .SYNOPSIS 
            Adds a file name extension to a supplied name.
            #>            
            function Add-Extension 
            {
                param ([string]$Name,[string]$Extension = "txt")
                ...
            } 

Чтобы отключить справку, заключите ее в here-строку, как показано в следующем примере:

            @"  
            <#
            .SYNOPSIS 
            Adds a file name extension to a supplied name.
            #>
            "@            
            function Add-Extension 
            {
                param ([string]$Name,[string]$Extension = "txt")
                ...
            }

Чтобы скрыть отключенную справку, присвойте here-строку локальной переменной, которая не используется в функции в других целях, как показано в следующем примере: Ее можно также передать по конвейеру в командлет Out-Null.

            $x = @"  
            <#
            .SYNOPSIS 
            Adds a file name extension to a supplied name.
            #>
            "@            
            function Add-Extension 
            {
                param ([string]$Name,[string]$Extension = "txt")
                ...
            }

Дополнительные сведения о here-строках см. в статье about_Quoting_Rules (https://go.microsoft.com/fwlink/?LinkID=113253).

ПРИМЕРЫ

Пример 1. Справка на основе комментариев по функции

Следующий пример функции содержит справку на основе комментариев:

            function Add-Extension 
            {
                param ([string]$Name,[string]$Extension = "txt")
                $name = $name + "." + $extension
                $name

            <#
            .SYNOPSIS 
            Adds a file name extension to a supplied name.

            .DESCRIPTION
            Adds a file name extension to a supplied name. 
            Takes any strings for the file name or extension.

            .PARAMETER Name
            Specifies the file name.

            .PARAMETER Extension
            Specifies the extension. "Txt" is the default.

            .INPUTS
            None. You cannot pipe objects to Add-Extension.

            .OUTPUTS
            System.String. Add-Extension returns a string with the extension or file name.

            .EXAMPLE
            C:\PS> extension -name "File"
            File.txt

            .EXAMPLE
            C:\PS> extension -name "File" -extension "doc"
            File.doc

            .EXAMPLE
            C:\PS> extension "File" "doc"
            File.doc

            .LINK
            http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
            }

Результаты:

        C:\PS> get-help add-extension -full

        NAME
            Add-Extension
    
        SYNOPSIS
            Adds a file name extension to a supplied name.
    
        SYNTAX
            Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]
    
        DESCRIPTION
            Adds a file name extension to a supplied name. Takes any strings for the file name or extension.
    
        PARAMETERS
           -Name
               Specifies the file name.
        
               Required?                    false
               Position?                    0
               Default value                
               Accept pipeline input?       false
               Accept wildcard characters?  
        
           -Extension
               Specifies the extension. "Txt" is the default.
        
               Required?                    false
               Position?                    1
               Default value                
               Accept pipeline input?       false
               Accept wildcard characters?  
        
            <CommonParameters>
               This cmdlet supports the common parameters: -Verbose, -Debug,
               -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
               -OutBuffer and -OutVariable. For more information, type
               "get-help about_commonparameters".
            INPUTs
            None. You cannot pipe objects to Add-Extension.
        OUTPUTS
            System.String. Add-Extension returns a string with the extension or file name.
            -------------------------- EXAMPLE 1 --------------------------
    
            C:\PS> extension -name "File"
            File.txt
    
            -------------------------- EXAMPLE 2 --------------------------
    
            C:\PS> extension -name "File" -extension "doc"
            File.doc
    
            -------------------------- EXAMPLE 3 --------------------------
    
            C:\PS> extension "File" "doc"
            File.doc
    
        RELATED LINKS
            http://www.fabrikam.com/extension.html
            Set-Item

Пример 2. Описания параметров в синтаксисе функции

Этот пример отличается от предыдущего только тем, что описания параметров в нем включены в синтаксис функции. Этот формат наиболее целесообразен, когда приводятся краткие описания.

        function Add-Extension 
        {
            param 
            (
                [string]
                # Specifies the file name.
                $name,

                [string]
                # Specifies the file name extension. \"Txt\" is the default.
                $extension = "txt"
            )
            $name = $name + "." + $extension
            $name
      
            <#
            .SYNOPSIS 
            Adds a file name extension to a supplied name.

            .DESCRIPTION
            Adds a file name extension to a supplied name. Takes any strings for the file name or extension.

            .INPUTS
            None. You cannot pipe objects to Add-Extension.

            .OUTPUTS
            System.String. Add-Extension returns a string with the extension or file name.

            .EXAMPLE
            C:\PS> extension -name "File"
            File.txt

            .EXAMPLE
            C:\PS> extension -name "File" -extension "doc"
            File.doc

            .EXAMPLE
            C:\PS> extension "File" "doc"
            File.doc
 
            .LINK
            http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
        }

Пример 3. Справка на основе комментариев по сценарию

Следующий пример сценария содержит справку на основе комментариев:

Обратите внимание на пустые строки между закрывающим символом "#>" и оператором Param. В сценарии без оператора Param должно быть не менее двух пустых строк между последним комментарием в разделе справки и первым объявлением функции. Без этих пустых строк командлет Get-Help связывает раздел справки с функцией, а не со сценарием.

           <#
           .SYNOPSIS 
           Performs monthly data updates.

           .DESCRIPTION
           The Update-Month.ps1 script updates the registry with new data generated
           during the past month and generates a report.
    
           .PARAMETER InputPath
           Specifies the path to the CSV-based input file.

           .PARAMETER OutputPath
           Specifies the name and path for the CSV-based output file. By default, 
           MonthlyUpdates.ps1 generates a name from the date and time it runs, and
           saves the output in the local directory.

           .INPUTS
           None. You cannot pipe objects to Update-Month.ps1.

           .OUTPUTS
           None. Update-Month.ps1 does not generate any output.

           .EXAMPLE
           C:\PS> .\Update-Month.ps1

           .EXAMPLE
           C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

           .EXAMPLE
           C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv
           #>

           param ([string]$InputPath, [string]$OutPutPath)

           function Get-Data { }
           ...

Следующая команда возвращает справку по сценарию. Так как в каталоге, указанном в переменной среды Path, сценарий отсутствует, команда Get-Help, которая возвращает справку по сценарию, должна указывать путь к нему.

            PS C:\ps-test> get-help .\update-month.ps1 -full
            NAME
                C:\ps-test\Update-Month.ps1
            SYNOPSIS
                Performs monthly data updates.
            SYNTAX
                C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
                <String>] [<CommonParameters>]
            DESCRIPTION
                The Update-Month.ps1 script updates the registry with new data
                generated during the past month and generates a report.
            PARAMETERS
               -InputPath
                   Specifies the path to the CSV-based input file.
        
                   Required?                    true
                   Position?                    0
                   Default value                
                   Accept pipeline input?       false
                   Accept wildcard characters?  
               -OutputPath
                   Specifies the name and path for the CSV-based output file. By
                   default, MonthlyUpdates.ps1 generates a name from the date
                   and time it runs, and saves the output in the local directory.
        
                   Required?                    false
                   Position?                    1
                   Default value                
                   Accept pipeline input?       false
                   Accept wildcard characters?  
               <CommonParameters>
                   This cmdlet supports the common parameters: -Verbose, -Debug,
                   -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
                   -OutBuffer and -OutVariable. For more information, type,
                   "get-help about_commonparameters".
            INPUTS
                   None. You cannot pipe objects to Update-Month.ps1.
            OUTPUTS
                   None. Update-Month.ps1 does not generate any output.
            -------------------------- EXAMPLE 1 --------------------------
        
            C:\PS> .\Update-Month.ps1
    
            -------------------------- EXAMPLE 2 --------------------------
       
            C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
    
            -------------------------- EXAMPLE 3 --------------------------
    
            C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath 
            C:\Reports\2009\January.csv
        
            RELATED LINKS

Пример 4. Перенаправление к XML-файлу

Разделы справки по функциям и сценариям можно создавать на основе XML. Хотя справку на основе комментариев реализовать проще, справка на основе XML необходима для обновляемой справки, чтобы разделы справки могли создаваться на различных языках.

В следующем примере показаны первые несколько строк сценария Update-Month.ps1. В сценарии используется ключевое слово ExternalHelp, которое указывает путь к разделу на справки на основе XML по сценарию.

Обратите внимание, что значение ключевого слова ExternalHelp находится с ним в одной строке. В любом другом положении это значение недействительно.

            #  .ExternalHelp C:\MyScripts\Update-Month-Help.xml

            param ([string]$InputPath, [string]$OutPutPath)
            function Get-Data { }
            ...

В следующем примере показаны три допустимых положения ключевого слова ExternalHelp в функции:

function Add-Extension 
            {
                # .ExternalHelp C:\ps-test\Add-Extension.xml

                param ([string] $name, [string]$extension = "txt")
                $name = $name + "." + $extension
                $name
            }
            
            function Add-Extension 
            {
                param ([string] $name, [string]$extension = "txt")
                $name = $name + "." + $extension
                $name
      
                # .ExternalHelp C:\ps-test\Add-Extension.xml
            }

           # .ExternalHelp C:\ps-test\Add-Extension.xml
           function Add-Extension 
            {
                param ([string] $name, [string]$extension = "txt")
                $name = $name + "." + $extension
                $name
            }

Пример 5. Перенаправление в другой раздел справки

Приведенный ниже код — это фрагмент начала встроенной функции справки в Windows PowerShell, которая одновременно выводит только одно окно текста справки. Так как в разделе справки по командлету Get-Help описывается функция справки, эта функция использует ключевые слова ForwardHelpTargetName и ForwardHelpCategory для перенаправления пользователя к разделу справки по командлету Get-Help.

            function help 
            {

            <#
            .FORWARDHELPTARGETNAME Get-Help
            .FORWARDHELPCATEGORY Cmdlet
            #>
            [CmdletBinding(DefaultParameterSetName='AllUsersView')]
            param(
                [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
                [System.String]
                ${Name},
                   ...

Эта функция используется в следующей команде:

            C:\PS> get-help help
            NAME
                Get-Help
            SYNOPSIS
                Displays information about Windows PowerShell cmdlets and concepts.
            ...

КЛЮЧЕВЫЕ СЛОВА

about_Comment Based_Help

СМ. ТАКЖЕ

about_Functions

about_Functions_Advanced_Parameters

about_Scripts

"Создание справки по командлетам" (https://go.microsoft.com/fwlink/?LinkID=123415)