O nápovědě na základě komentářů

KRÁTKÝ POPIS

Popisuje, jak psát témata nápovědy na základě komentářů pro funkce a skripty.

DLOUHÝ POPIS

Témata nápovědy na základě komentářů můžete napsat pro funkce a skripty pomocí speciálních klíčových slov pro komentáře nápovědy.

Rutina Get-Help zobrazuje nápovědu založenou na komentářích ve stejném formátu, ve kterém zobrazuje témata nápovědy k rutinám, které jsou generovány ze souborů XML. Uživatelé můžou Get-Help k zobrazení obsahu nápovědy založené na komentářích použít všechny parametry, jako jsou například podrobné, úplné, Příkladya online.

Můžete také zapisovat soubory s nápovědu založené na jazyce XML pro funkce a skripty. Chcete-li povolit Get-Help rutině vyhledat soubor nápovědu založený na jazyce XML pro funkci nebo skript, použijte klíčové slovo "ExternalHelp". 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, najdete v tématu Get-Help.

Rutiny Update-Help a Save-Help fungují pouze v souborech XML. Aktualizovatelná pomoc nepodporuje témata nápovědy na základě komentářů.

SYNTAXE PRO NÁPOVĚDU ZALOŽENOU NA KOMENTÁŘÍCH

Syntaxe pro nápovědu na základě komentářů je následující:

.<help keyword>
<help content>

nebo

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

Pomocí komentáře se zapisuje jako řada komentářů. Symbol komentáře můžete zadat # před každým řádkem komentářů nebo můžete použít <# #> symboly a k vytvoření bloku komentáře. Všechny řádky v bloku komentáře jsou interpretovány jako komentáře.

Všechny řádky v tématu nápovědy založeném na komentářích musí být souvislé. Pokud se v tématu nápovědy na základě komentářů zobrazuje komentář, který není součástí tématu nápovědy, musí existovat alespoň jeden prázdný řádek mezi posledním řádkem poznámky mimo nápovědu a začátkem nápovědy založené na komentářích.

Klíčová slova definují jednotlivé části pomocníka založené na komentářích. Na každé klíčové slovo s popisem komentáře je uvedena tečka . . Klíčová slova se mohou zobrazit v libovolném pořadí. V názvech klíčových slov se nerozlišují malá a velká písmena.

Například klíčové slovo Description 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 ve stejném bloku komentáře vyskytovat mnohokrát. Obsah v nápovědě pro každé klíčové slovo začíná na řádku za klíčovým slovem a může zahrnovat více řádků.

SYNTAXE PRO NÁPOVĚDU NA ZÁKLADĚ KOMENTÁŘŮ VE FUNKCÍCH

Pro funkci se může v jednom ze tří umístění zobrazit nápovědu na základě komentářů:

• Na začátku těla funkce.
• Na konci těla funkce.
• Před klíčovým slovem Function. Mezi posledním řádkem funkce Help a klíčovým slovem Function nelze zadat 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 PRO NÁPOVĚDU NA ZÁKLADĚ KOMENTÁŘŮ VE SKRIPTECH

V jednom z následujících dvou umístění ve skriptu se může zobrazit nápovědu na základě komentářů ke skriptu.

• Na začátku souboru skriptu. Skriptové nápovědě lze předcházet pouze pomocí komentářů a prázdných řádků.

  Pokud je první položka v těle skriptu (po nápovědě) deklarací funkce, musí existovat alespoň dva prázdné řádky mezi koncem Help Script a deklarací funkce. V opačném případě je tato nápovědu interpretována jako nápovědu pro funkci, nikoli pro skript.

• Na konci souboru skriptu. Pokud je však skript podepsaný, na začátek souboru skriptu umístěte technickou podporu na základě komentářů. Konec skriptu je obsazený blokem signatury.

Příklad:

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


function Get-Function { }

nebo

function Get-Function { }

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

SYNTAXE PRO NÁPOVĚDU NA ZÁKLADĚ KOMENTÁŘŮ VE SKRIPTOVACÍCH MODULECH

V modulu skriptu .psm1 používá nápovědu na základě komentářů syntaxi pro funkce, nikoli syntaxi pro skripty. Pomocí syntaxe skriptu nelze poskytnout nápovědu pro všechny funkce definované v modulu skriptu.

Například pokud používáte klíčové slovo "ExternalHelp" k identifikaci souborů pomoci založených na jazyce XML pro funkce v modulu skriptu, je nutné do každé funkce Přidat komentář "ExternalHelp".

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

KLÍČOVÁ SLOVA PRO NÁPOVĚDĚ NA ZÁKLADĚ KOMENTÁŘŮ

Níže jsou platná klíčová slova pomocníka na základě komentářů. 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 zobrazit v libovolném pořadí a nerozlišují se malá a velká písmena.

. Stručný obsah

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

. NÁZEV

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

. UKAZATELE

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

Zadejte název parametru na stejném řádku jako ". PARAMETR "klíčové slovo". Zadejte popis parametru na řádcích následujících po ". PARAMETR "klíčové slovo". Prostředí Windows PowerShell interpretuje veškerý text mezi ". PARAMETR "line a Next klíčové slovo nebo konec bloku komentáře jako součást popisu parametru. Popis může zahrnovat konce odstavců.

.PARAMETER  <Parameter-Name>

Klíčová slova parametrů se mohou v bloku komentáře zobrazit v libovolném pořadí, ale funkce nebo syntaxe skriptu určuje pořadí, ve kterém jsou parametry (a jejich popisy) zobrazeny v tématu nápovědy. Chcete-li změnit pořadí, změňte syntaxi.

Můžete také zadat popis parametru umístěním komentáře do syntaxe funkce nebo skriptu bezprostředně před názvem proměnné parametru. Použijete-li komentář syntaxe a klíčové slovo parametru, je použit popis přidružený k klíčovému slovu Parameter a komentář syntaxe je ignorován.

. PŘÍPADĚ

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

. VZTAHUJÍ

Microsoft .NET Framework typy objektů, které lze přesměrovat do funkce nebo skriptu. Můžete také zahrnout popis vstupních objektů.

. ČINNOSTI

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

. Poznámka

Další informace o funkci nebo skriptu.

. PROPOJIT

Název souvisejícího tématu. Hodnota se zobrazí na řádku pod ". Klíčové slovo LINK a musí předcházet symbol komentáře # nebo obsaženo v bloku komentáře.

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

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

Obsah klíčového slova "propojit" 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 při použití parametru online Get-Help . Identifikátor URI musí začínat řetězcem "http" nebo "https".

. ČÁST

Technologie nebo funkce, kterou funkce nebo skript používá nebo ke které se vztahuje. Tento obsah se zobrazí, pokud Get-Help příkaz obsahuje parametr komponenty Get-Help .

. ROLE

Role uživatele pro téma nápovědy Tento obsah se zobrazí, pokud Get-Help příkaz obsahuje parametr role Get-Help .

. MOŽNOST

Zamýšlené použití funkce. Tento obsah se zobrazí, pokud Get-Help příkaz obsahuje parametr funkce 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 Help položky v "ForwardHelpTargetName". Platné hodnoty jsou "alias", "rutina", "soubor nápovědy", "Function", "Provider", "General", "FAQ", "Glosář", "ScriptCommand", "ExternalScript", "Filter" nebo "All". Toto klíčové slovo použijte, pokud chcete zabránit 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 "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ědu založený na jazyce XML pro skript nebo funkci.

# .EXTERNALHELP <XML Help File>

Klíčové slovo "ExternalHelp" 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 s podporou XML pro funkci nebo skript.

Klíčové slovo "ExternalHelp" má přednost před dalšími klíčovými slovy pomocníka založenými na komentářích. Pokud je k dispozici "ExternalHelp", Get-Help nezobrazuje nápovědu na základě komentářů ani v případě, že nemůže najít téma nápovědy, které odpovídá hodnotě klíčového slova "ExternalHelp".

Pokud je funkce exportována modulem, nastavte hodnotu klíčového slova "ExternalHelp" na název souboru bez cesty. Get-HelpVyhledá zadaný název souboru v podadresáři adresáře modulu specifického pro jazyk. Pro funkci nejsou k dispozici žádné požadavky na název souboru Help založeného na jazyce XML, ale doporučujeme použít následující formát:

<ScriptModule.psm1>-help.xml

Pokud funkce není zahrnuta v modulu, zahrňte cestu k souboru Help založenému na XML. Pokud hodnota zahrnuje cestu a cesta obsahuje podadresáře specifické pro jazykovou verzi, Get-Help vyhledává podadresáře rekurzivně pro soubor XML s názvem skriptu nebo funkcí v souladu se základními jazykovými standardy, které jsou vytvořeny pro systém Windows, stejně jako v adresáři modulu.

Další informace o formátu souboru Help v nápovědě k rutině založené na XML naleznete v tématu Jak napsat nápovědu k rutinám v knihovně MSDN.

AUTOMATICKY VYGENEROVANÝ OBSAH

Název, syntaxe, seznam parametrů, tabulka atributu parametru, společné parametry a poznámky jsou automaticky generovány Get-Help rutinou.

Name

Oddíl "Name" tématu nápovědy funkce je pořízen z názvu funkce v syntaxi funkce. Název tématu nápovědy ke skriptu je pořízen z názvu souboru skriptu. Chcete-li změnit název nebo jeho velká písmena, změňte syntaxi funkce nebo název souboru skriptu.

Syntaxe

Oddíl "syntax" v tématu nápovědy je vygenerován z syntaxe funkce nebo skriptu. Chcete-li přidat podrobnosti do syntaxe tématu nápovědy, jako je například .NET Framework typ parametru, přidejte podrobnosti do syntaxe. Pokud nezadáte typ parametru, je jako výchozí hodnota vložen typ Object.

Seznam parametrů

Seznam parametrů v tématu nápovědy je vygenerován z syntaxe Function nebo Script a z popisů, které přidáte pomocí klíčového slova Parameters. Parametry funkce se zobrazí v části Parameters tématu nápovědy ve stejném pořadí, v jakém jsou uvedeny v syntaxi funkce nebo skriptu. Pravopis a velká písmena názvů parametrů jsou také získány ze syntaxe; není ovlivněný názvem parametru zadaným klíčovým slovem Parameter.

Společné parametry

"Společné parametry" jsou přidány do seznamu syntaxe a parametrů v tématu nápovědy, i když nemají žádný vliv. Další informace o běžných parametrech naleznete v tématu about_CommonParameters.

Tabulka atributů parametru

Get-Helpvygeneruje tabulku atributů parametrů, které se zobrazí, když použijete úplný parametr nebo a parametr Get-Help . Hodnota atributu "Required", "Position" a "default" se převezme z syntaxe funkce nebo skriptu.

Výchozí hodnoty a hodnota "přijmout zástupné znaky" se nezobrazí v tabulce atributů parametrů, i když jsou definovány ve funkci nebo skriptu. Chcete-li uživatelům pomáhat, poskytněte tyto informace v popisu parametru.

Poznámky

Část "poznámky" v tématu nápovědy je automaticky vygenerována z názvu funkce nebo skriptu. Nemůžete změnit nebo ovlivnit jeho obsah.

PŘÍKLADY

Poznámková nápovědě pro funkci

Následující ukázková funkce obsahuje podporu na základě komentářů:

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ší, když 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ědu na základě komentářů ke skriptu

Následující vzorový skript obsahuje podporu na základě komentářů. Všimněte si prázdných řádků mezi uzávěrkou #> a Param příkazem. Ve skriptu, který nemá Param příkaz, musí existovat alespoň dva prázdné řádky mezi konečný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 ke skriptu.

<#
.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 zobrazí informace o skriptu. Protože skript není v adresáři, který je uveden v proměnné prostředí "path", Get-Help příkaz, který získá nápovědě ke skriptu, musí určovat cestu ke skriptu.

Get-Help -Path .\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 XML můžete napsat pro funkce a skripty. I když je snazší implementovat nápovědu založenou na komentářích, potřebujete nápovědu založenou na jazyce XML, která umožňuje aktualizovatelné nápovědy a poskytuje témata nápovědy v několika jazycích.

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

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

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

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

Následující příklady znázorňují tři platná umístění klíčového slova "ExternalHelp" 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 ze začátku předdefinované funkce Help v prostředí PowerShell, která zobrazuje jednu obrazovku textu v nápovědě. Vzhledem k tomu, že téma nápovědy pro Get-Help rutinu popisuje funkci nápovědy, funkce nápovědy používá klíčová slova "ForwardHelpTargetName" a "ForwardHelpCategory" k přesměrování uživatele do Get-Help tématu nápovědy k rutině.

function help
{

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

Tuto funkci používá následující příkaz:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

VIZ TAKÉ

about_Functions

about_Functions_Advanced_Parameters

about_Scripts

Psaní rutiny Help