about_Comment_Based_Help

Článek
10/04/2023

Krátký popis

Popisuje, jak psát témata nápovědy založené na komentářích pro funkce a skripty.

Dlouhý popis

Témata nápovědy založené na komentářích pro funkce a skripty můžete psát pomocí speciálních klíčových slov komentářů nápovědy.

Rutina Get-Help zobrazí nápovědu založenou na komentářích ve stejném formátu, ve kterém zobrazuje témata nápovědy rutiny generovaná ze souborů XML. Uživatelé můžou k zobrazení obsahu nápovědy založené na komentářích použít všechny parametry Get-Help, například Podrobné, Úplné, Příklady a Online.

Můžete také napsat soubory nápovědy založené na JAZYCE XML pro funkce a skripty. Pokud chcete rutině Get-Help povolit vyhledání souboru nápovědy založeného na jazyce XML pro funkci nebo skript, použijte .ExternalHelp klíčové slovo. Bez tohoto klíčového slova Get-Help nelze najít témata nápovědy založená na jazyce XML pro funkce nebo skripty.

Toto téma vysvětluje, jak psát témata nápovědy pro funkce a skripty. Informace o tom, jak zobrazit témata nápovědy pro funkce a skripty, naleznete v tématu Získat nápovědu.

Rutiny Update-Help a Save-Help fungují jenom u souborů XML. Aktualizovatelná nápověda nepodporuje témata nápovědy založené na komentářích.

Syntaxe nápovědy založené na komentářích

Syntaxe nápovědy založené na komentářích je následující:

# .<help keyword>
# <help content>

nebo

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

Nápověda založená na komentářích je napsána jako řada komentářů. Před každý řádek komentářů můžete napsat symbol # komentáře nebo můžete pomocí <##> symbolů vytvořit blok komentáře. Všechny řádky v bloku komentáře se interpretují jako komentáře.

Všechny řádky v tématu nápovědy založeném na komentářích musí být souvislé. Pokud téma nápovědy založené na komentáři následuje za komentářem, který není součástí tématu nápovědy, musí existovat alespoň jeden prázdný řádek mezi posledním řádkem komentáře bez nápovědy a začátkem nápovědy založené na komentáři.

Klíčová slova definují jednotlivé části nápovědy založené na komentářích. Každé klíčové slovo nápovědy založené na komentářích předchází tečka .. Klíčová slova se můžou zobrazit v libovolném pořadí. V názvech klíčových slov se nerozlišují malá a velká písmena.

Například .Description klíčové slovo předchází popisu funkce nebo skriptu.

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

Blok komentáře musí obsahovat alespoň jedno klíčové slovo. Některá klíčová slova, například .EXAMPLE, se můžou objevit mnohokrát ve stejném bloku komentáře. Obsah nápovědy pro každé klíčové slovo začíná na řádku za klíčovým slovem a může obsahovat více řádků.

Syntaxe nápovědy založené na komentářích ve funkcích

Nápověda pro funkci založená na komentářích se může zobrazit na jednom ze tří míst:

Na začátku těla funkce.
Na konci těla funkce.
Před klíčovým slovem function . Mezi posledním řádkem nápovědy funkce a klíčovým slovem function nemůže být více než jeden prázdný řádek.

Příklad:

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

  # function logic
}

nebo

function Get-Function
{
   # function logic

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

nebo

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

Syntaxe nápovědy založené na komentářích ve skriptech

Nápověda pro skript založená na komentářích se může zobrazit v jednom z následujících dvou umístění skriptu.

Na začátku souboru skriptu. Nápovědu ke skriptu můžou předcházet jenom komentáře a prázdné řádky.

Pokud první položka v těle skriptu (po nápovědě) je deklarace funkce, musí existovat alespoň dva prázdné řádky mezi koncem nápovědy skriptu a deklarací funkce. Jinak se nápověda interpretuje jako nápověda pro funkci, nikoli jako nápověda pro skript.
Na konci souboru skriptu. Pokud je však skript podepsaný, umístěte na začátek souboru skriptu nápovědu založenou na komentáři. Konec skriptu je obsazen blokem podpisu.

Příklad:

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


function Get-Function { }

nebo

function Get-Function { }

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

Syntaxe nápovědy založené na komentářích v modulech skriptů

V modulu .psm1skriptu používá nápověda založená na komentářích syntaxi pro funkce, nikoli syntaxi pro skripty. Syntaxi skriptu nelze použít k poskytnutí nápovědy pro všechny funkce definované v modulu skriptu.

Pokud například používáte .ExternalHelp klíčové slovo k identifikaci souborů nápovědy založených na JAZYCE XML pro funkce v modulu skriptu, musíte ke každé funkci přidat .ExternalHelp komentář.

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

Klíčová slova nápovědy založené na komentářích

Následují platná klíčová slova nápovědy založené na komentářích. Jsou uvedeny v pořadí, ve kterém se obvykle zobrazují v tématu nápovědy spolu s zamýšleným použitím. Tato klíčová slova se můžou v nápovědě založené na komentářích zobrazovat v libovolném pořadí a nerozlišují malá a velká písmena.

.SYNOPSIS

Stručný popis funkce nebo skriptu. Toto klíčové slovo lze použít pouze jednou v každém tématu.

.DESCRIPTION

Podrobný popis funkce nebo skriptu Toto klíčové slovo lze použít pouze jednou v každém tématu.

.PARAMETER

Popis parametru. .PARAMETER Přidejte klíčové slovo pro každý parametr v syntaxi funkce nebo skriptu.

Zadejte název parametru .PARAMETER na stejný řádek jako klíčové slovo. Zadejte popis parametru na řádcích za klíčovým slovem .PARAMETER . Windows PowerShell interpretuje veškerý text mezi řádkem .PARAMETER a dalším klíčovým slovem nebo koncem bloku komentáře jako součást popisu parametru. Popis může obsahovat konce odstavců.

.PARAMETER  <Parameter-Name>

Klíčová slova parametru se můžou v bloku komentáře zobrazovat v libovolném pořadí, ale funkce nebo syntaxe skriptu určuje pořadí, ve kterém se parametry (a jejich popisy) zobrazují v tématu nápovědy. Pokud chcete změnit pořadí, změňte syntaxi.

Popis parametru můžete také zadat umístěním komentáře do syntaxe funkce nebo skriptu bezprostředně před název proměnné parametru. Aby to fungovalo, musíte mít blok komentáře s alespoň jedním klíčovým slovem.

Pokud použijete komentář syntaxe i .PARAMETER klíčové slovo, použije se popis přidružený ke klíčovému .PARAMETER slovu a komentář syntaxe se ignoruje.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .Parameter
        [string]$Computername
    )
    # Verb the Noun on the computer
}

.EXAMPLE

Ukázkový příkaz, který používá funkci nebo skript, volitelně následovaný ukázkovým výstupem a popisem. Opakujte toto klíčové slovo pro každý příklad.

.INPUTS

Typy objektů .NET, které lze předvést do funkce nebo skriptu. Můžete také zahrnout popis vstupních objektů.

.OUTPUTS

Typ .NET objektů, které rutina vrací. Můžete také zahrnout popis vrácených objektů.

.NOTES

Další informace o funkci nebo skriptu

.LINK

Název souvisejícího tématu. Hodnota se zobrazí na řádku pod klíčovým slovem ".LINK" a musí před ní být symbol # komentáře nebo zahrnutý do bloku komentáře.

.LINK Opakujte klíčové slovo pro každé související téma.

Tento obsah se zobrazí v části Související odkazy tématu nápovědy.

Obsah .Link klíčového slova může také obsahovat identifikátor URI (Uniform Resource Identifier) do online verze stejného tématu nápovědy. Online verze se otevře, když použijete parametr Get-Help. Identifikátor URI musí začínat řetězcem http nebo https.

.COMPONENT

Název technologie nebo funkce, kterou funkce nebo skript používá nebo ke které souvisí. Parametr ComponentGet-Help pro použití této hodnoty k filtrování výsledků hledání vrácených Get-Help.

.ROLE

Název role uživatele pro téma nápovědy. Parametr Get-Help role používá tuto hodnotu k filtrování výsledků hledání vrácených .Get-Help

.FUNCTIONALITY

Klíčová slova, která popisují zamýšlené použití funkce. Parametr Get-Help Funkce používá tuto hodnotu k filtrování výsledků hledání vrácených .Get-Help

.FORWARDHELPTARGETNAME

Přesměruje se na téma nápovědy pro zadaný příkaz. Uživatele můžete přesměrovat na jakékoli téma nápovědy, včetně témat nápovědy pro funkci, skript, rutinu nebo poskytovatele.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Určuje kategorii nápovědy položky v souboru .ForwardHelpTargetName. Platné hodnoty jsou Alias, Cmdlet, , HelpFile, ProviderGlossaryGeneralFunctionScriptCommandExternalScriptFAQ, , Filter, nebo .All Pomocí tohoto klíčového slova se vyhnete konfliktům, pokud existují příkazy se stejným názvem.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Určuje relaci, která obsahuje téma nápovědy. Zadejte proměnnou , která obsahuje objekt PSSession . Toto klíčové slovo používá rutina Export-PSSession k vyhledání témat nápovědy pro exportované příkazy.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Určuje soubor nápovědy založený na jazyce XML pro skript nebo funkci.

# .EXTERNALHELP <XML Help File>

Klíčové .ExternalHelp slovo je vyžadováno, pokud je funkce nebo skript dokumentován v souborech XML. Bez tohoto klíčového slova Get-Help nelze najít soubor nápovědy založený na jazyce XML pro funkci nebo skript.

Klíčové .ExternalHelp slovo má přednost před jinými klíčovými slovy nápovědy založené na komentářích. Pokud .ExternalHelp je k dispozici, Get-Help nezobrazuje nápovědu založenou na komentáři, i když nemůže najít téma nápovědy, které odpovídá hodnotě klíčového .ExternalHelp slova.

Pokud je funkce exportována modulem, nastavte hodnotu klíčového .ExternalHelp slova na název souboru bez cesty. Get-Help Vyhledá zadaný název souboru v podadresáři modulu specifickém pro jazyk. Pro název souboru nápovědy založeného na jazyce XML pro funkci neexistují žádné požadavky, ale osvědčeným postupem je použít následující formát:

<ScriptModule.psm1>-help.xml

Pokud funkce není součástí modulu, zahrňte cestu k souboru nápovědy založenému na JAZYCE XML. Pokud hodnota obsahuje cestu a cesta obsahuje podadresáře specifické pro ui-culture, Get-Help prohledá podadresáře rekurzivně pro soubor XML s názvem skriptu nebo funkce v souladu se standardy pro návrat jazyka vytvořenými pro Windows, stejně jako to dělá v adresáři modulu.

Další informace o formátu souboru nápovědy XML nápovědy rutiny naleznete v tématu Jak napsat nápovědu rutiny.

Automaticky vygenerovaný obsah

Rutina Get-Help automaticky vygeneruje název, syntaxi, seznam parametrů, tabulku atributů parametrů, běžné parametry a poznámky.

Název

Část Název tématu nápovědy funkce je převzata z názvu funkce v syntaxi funkce. Název tématu nápovědy ke skriptu se přebírá z názvu souboru skriptu. Pokud chcete změnit název nebo jeho velká písmena, změňte syntaxi funkce nebo název souboru skriptu.

Syntaxe

Část Syntaxe tématu nápovědy se generuje z syntaxe funkce nebo skriptu. Pokud chcete přidat podrobnosti do syntaxe tématu nápovědy, například typ .NET parametru, přidejte do syntaxe podrobnosti. Pokud nezadáte typ parametru , vloží se jako výchozí hodnota typ objektu .

Seznam parametrů

Seznam parametrů v tématu nápovědy se generuje ze syntaxe funkce nebo skriptu a z popisů, které přidáte pomocí klíčového .Parameter slova. Parametry funkce se zobrazí v části Parametry tématu nápovědy ve stejném pořadí, v jakém se zobrazují v syntaxi funkce nebo skriptu. Pravopis a velká písmena názvů parametrů jsou převzaty také ze syntaxe. Není ovlivněn názvem parametru určeným klíčovým slovem .Parameter .

Běžné parametry

Běžné parametry se přidají do syntaxe a seznamu parametrů tématu nápovědy, i když nemají žádný vliv. Další informace o běžných parametrech najdete v tématu about_CommonParameters.

Tabulka atributů parametru

Get-Help vygeneruje tabulku atributů parametrů, které se zobrazí při použití Full nebo Parametr parametru Get-Help. Hodnota atributu Required, Position a Default value je převzata z funkce nebo syntaxe skriptu.

Výchozí hodnoty a hodnota pro Accept Wildcard se nezobrazují v tabulce atributů parametrů, i když jsou definovány ve funkci nebo skriptu. Pokud chcete uživatelům pomoct, zadejte tyto informace v popisu parametru.

Poznámky

Oddíl Poznámky tématu nápovědy se automaticky vygeneruje z názvu funkce nebo skriptu. Obsah nelze změnit ani ovlivnit.

Příklady

Nápověda založená na komentářích pro funkci

Následující ukázková funkce obsahuje nápovědu založenou na komentářích:

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

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

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

.LINK

Set-Item
#>
}

Výsledky jsou následující:

Get-Help -Name "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

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

Popisy parametrů v syntaxi funkce

Tento příklad je stejný jako předchozí, s tím rozdílem, že popisy parametrů jsou vloženy do syntaxe funkce. Tento formát je nejužitečnější, pokud jsou popisy stručné.

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

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

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

.LINK

Set-Item
#>
}

Nápověda založená na komentářích pro skript

Následující ukázkový skript obsahuje nápovědu založenou na komentářích. Všimněte si prázdných řádků mezi závěrem #> a příkazem Param . Ve skriptu, který neobsahuje Param příkaz, musí existovat alespoň dva prázdné řádky mezi posledním komentářem v tématu nápovědy a první deklarací funkce. Bez těchto prázdných řádků Get-Help přidruží téma nápovědy k funkci, nikoli skript.

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

PS> .\Update-Month.ps1

.EXAMPLE

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

.EXAMPLE

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

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

function Get-Data { }
...

Následující příkaz získá nápovědu ke skriptu. Vzhledem k tomu, že skript není v adresáři, který je uveden v $env:Path proměnné prostředí, Get-Help musí příkaz, který získá nápovědu skriptu, zadat cestu ke skriptu.

Get-Help -Name .\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

PS> .\Update-Month.ps1

Example 2

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

Example 3

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

# RELATED LINKS

Přesměrování na soubor XML

Témata nápovědy založené na jazyce XML můžete psát pro funkce a skripty. I když je pomoc založená na komentářích jednodušší implementovat, pro aktualizovatelnou nápovědu a k poskytování témat nápovědy ve více jazycích se vyžaduje nápověda založená na jazyce XML.

Následující příklad ukazuje několik prvních řádků skriptu Update-Month.ps1. Skript pomocí klíčového .ExternalHelp slova určuje cestu k tématu nápovědy založenému na jazyce XML pro skript.

Všimněte si, že hodnota klíčového .ExternalHelp slova se zobrazí na stejném řádku jako klíčové slovo. Jakékoli jiné umístění je neefektivní.

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

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

Následující příklady ukazují tři platná umístění klíčového .ExternalHelp slova ve funkci.

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
}

Přesměrování na jiné téma nápovědy

Následující kód je výňatek od začátku integrované funkce nápovědy v PowerShellu, která zobrazuje najednou jednu obrazovku textu nápovědy. Protože téma nápovědy pro Get-Help rutinu popisuje funkci nápovědy, funkce nápovědy používá k přesměrování uživatele do Get-Help tématu nápovědy rutiny .ForwardHelpTargetName klíčová slova a .ForwardHelpCategory klíčová slova.

function help
{

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

Následující příkaz používá tuto funkci:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

about_Comment_Based_Help

Krátký popis

Dlouhý popis

Syntaxe nápovědy založené na komentářích

Syntaxe nápovědy založené na komentářích ve funkcích

Syntaxe nápovědy založené na komentářích ve skriptech

Syntaxe nápovědy založené na komentářích v modulech skriptů

Klíčová slova nápovědy založené na komentářích

.SYNOPSIS

.DESCRIPTION

.PARAMETER

.EXAMPLE

.INPUTS

.OUTPUTS

.NOTES

.LINK

.COMPONENT

.ROLE

.FUNCTIONALITY

.FORWARDHELPTARGETNAME

.FORWARDHELPCATEGORY

.REMOTEHELPRUNSPACE

.EXTERNALHELP

Automaticky vygenerovaný obsah

Název

Syntaxe

Seznam parametrů

Běžné parametry

Tabulka atributů parametru

Poznámky

Příklady

Nápověda založená na komentářích pro funkci

Popisy parametrů v syntaxi funkce

Nápověda založená na komentářích pro skript

Přesměrování na soubor XML

Přesměrování na jiné téma nápovědy

Viz také

Váš názor

Další materiály