Feedback

A. Comment-Based Hjälp

  • Artikel
  • 4 minuter för att läsa

PowerShell tillhandahåller en mekanism för programmerare som dokumenterar sina skript med hjälp av särskilda kommentarsdirektiv. Kommentarer som använder sådan syntax kallas hjälpkommentarer. Cmdleten Get-Help genererar dokumentation från dessa direktiv.

Introduktion till A.1

En hjälpkommentar innehåller ett hjälpdirektiv av formuläret . följt av en eller flera efterföljande rader med hjälpinnehållstexten. Hjälpkommentaren kan består av en serie med en radkommentarer eller en avgränsad kommentar (2.2.3). Den uppsättning kommentarer som består av dokumentationen för en enskild entitet kallas för ett hjälpavsnitt.

Exempel:

# <help-directive-1>
# <help-content-1>
...

# <help-directive-n>
# <help-content-n>

eller

<#
<help-directive-1>
<help-content-1>
...

<help-directive-n>
<help-content-n>
#>

Alla rader i ett hjälpavsnitt måste vara sammanhängande. Om ett hjälpavsnitt följer en kommentar som inte är en del av det ämnet måste det finnas minst en tom rad mellan de två.

-direktivet kan visas i valfri ordning och vissa av direktiv kan förekomma flera gånger.

Direktivnamn är inte fallkänsliga.

När du dokumenterar en funktion kan hjälpavsnitt visas på någon av tre platser:

  • Omedelbart före funktionsdefinitionen med högst en tom rad mellan den sista raden i funktionshjälpen och raden som innehåller funktionssatsen.
  • Inuti funktionens brödtext direkt efter den inledande klammern.
  • Inuti funktionens brödtext omedelbart före den avslutande klammern.

När du dokumenterar en skriptfil kan hjälpavsnitt visas på någon av två platser:

  • I början av skriptfilen kan det eventuellt föregås av kommentarer och tomma rader. Om det första objektet i skriptet efter hjälpen är en funktionsdefinition måste det finnas minst två tomma rader mellan slutet av skripthjälpen och funktionsdeklarationen. Annars tolkas hjälpen som att den tillämpas på funktionen i stället för på skriptfilen.
  • I slutet av skriptfilen.

A.2-hjälpdirektiv

A.2.1 . BESKRIVNING

Syntax:

.DESCRIPTION

Beskrivning:

Det här direktivet tillåter en detaljerad beskrivning av funktionen eller skriptet. (Direktivet .SYNOPSIS (·A.2.11) är avsett för en kort beskrivning.) Det här direktivet kan bara användas en gång i varje ämne.

Exempel:

<#
.DESCRIPTION
Computes Base to the power Exponent. Supports non-negative integer
powers only.
#>

A.2.2 . EXEMPEL

Syntax:

.EXAMPLE

Beskrivning:

Med det här direktivet kan ett exempel på kommandoanvändning visas.

Om det här direktivet inträffar flera gånger visas varje associerat hjälpinnehållsblock som ett separat exempel.

Exempel:

<#
.EXAMPLE
Get-Power 3 4
81

.EXAMPLE
Get-Power -Base 3 -Exponent 4
81
#>

A.2.3 . EXTERNALHELP

Syntax:

.EXTERNALHELP <XMLHelpFilePath>

Beskrivning:

Det här direktivet anger sökvägen till en XML-baserad hjälpfil för skriptet eller funktionen.

Även om kommentarsbaserad hjälp är enklare att implementera krävs XML-baserad hjälp om mer exakt kontroll krävs över hjälpinnehåll eller om hjälpämnen ska översättas till flera språk. Informationen om XML-baserad hjälp definieras inte av den här specifikationen.

Exempel:

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

A.2.4 . FORWARDHELPCATEGORY

Syntax:

.FORWARDHELPCATEGORY <Category>

Beskrivning:

Anger hjälpkategorin för objektet i ForwardHelpTargetName (\A.2.5). Giltiga värden är Alias, Alla, Cmdlet, ExternalScript, Faq, Filter, Function, General, Glossary, HelpFile, Provider och ScriptCommand. Använd det här direktivet för att undvika konflikter när det finns kommandon med samma namn.

Exempel:

Mer information finns i .A.2.5.

A.2.5 . FORWARDHELPTARGETNAME

Syntax:

.FORWARDHELPTARGETNAME <Command-Name>

Beskrivning:

Omdirigerar till hjälpavsnittet som anges av <Command-Name>.

Exempel:

function Help {
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
    ...
}

Kommandot behandlas Get-Help help som om det vore det i Get-Help Get-Help stället.

A.2.6 . INGÅNGAR

Syntax:

.INPUTS

Beskrivning:

Pipelinen kan användas för att skicka ett eller flera objekt till ett skript eller en funktion. Det här direktivet används för att beskriva sådana objekt och deras typer.

Om det här direktivet inträffar flera gånger samlas varje associerat hjälpinnehållsblock in i den enda dokumentationsposten, i direktivets lexikala ordning.

Exempel:

<#
.INPUTS
None. You cannot pipe objects to Get-Power.

.INPUTS
For the Value parameter, one or more objects of any kind can be written
to the pipeline. However, the object is converted to a string before it
is added to the item.
#>
function Process-Thing {
    param ( ...
        [Parameter(ValueFromPipeline=$true)]
        [object[]]$Value,
        ...
    )
    ...
}

Syntax:

.LINK

Beskrivning:

Det här direktivet anger namnet på ett relaterat ämne.

Om det här direktivet inträffar flera gånger samlas varje associerat hjälpinnehållsblock in i den enda dokumentationsposten, i direktivets lexikala ordning.

Innehållet i länkdirektivet kan också innehålla en URI till en onlineversion av samma hjälpavsnitt. Onlineversionen öppnas när Get-Help anropas med onlineparametern. URI:en måste börja med "http" eller "https".

Exempel:

<#
.LINK
Online version: http://www.acmecorp.com/widget.html

.LINK
Set-ProcedureName
#>

A.2.8 . ANTECKNINGAR

Syntax:

.NOTES

Beskrivning:

Med det här direktivet kan ytterligare information om funktionen eller skriptet tillhandahållas. Det här direktivet kan bara användas en gång i varje ämne.

Exempel:

<#
.Notes
*arbitrary text goes here*
#>

A.2.9 . UTGÅNGAR

Syntax:

.OUTPUTS

Beskrivning:

Det här direktivet används för att beskriva objektutdata med ett kommando.

Om det här direktivet inträffar flera gånger samlas varje associerat hjälpinnehållsblock in i den enda dokumentationsposten, i direktivets lexikala ordning.

Exempel:

<#
.OUTPUTS
double - Get-Power returns Base to the power Exponent.

.OUTPUTS
None unless the -PassThru switch parameter is used.
#>

A.2.10 . PARAMETERN

Syntax:

.PARAMETER <Parameter-Name>

Beskrivning:

Det här direktivet tillåter en detaljerad beskrivning av den angivna parametern. Det här direktivet kan användas en gång för varje parameter. Parameterdirektiv kan visas i valfri ordning i kommentarsblocket. I vilken ordning deras motsvarande parametrar faktiskt definieras i källan avgör dock i vilken ordning parametrarna och deras beskrivningar visas i den resulterande dokumentationen.

Ett alternativt format innebär att en parameterbeskrivningskommentar placeras omedelbart före deklarationen av motsvarande parametervariabels namn. Om källan innehåller både en parameterbeskrivningskommentar och ett parameterdirektiv används beskrivningen som är associerad med parameterdirektivet.

Exempel:

<#
.PARAMETER Base
The integer value to be raised to the Exponent-th power.

.PARAMETER Exponent
The integer exponent to which Base is to be raised.
#>

function Get-Power {
    param ([long]$Base, [int]$Exponent)
    ...
}

function Get-Power {
    param ([long]
        # The integer value to be raised to the Exponent-th power.
        $Base,
        [int]
        # The integer exponent to which Base is to be raised.
        $Exponent
    )
    ...
}

A.2.11 . SYNOPSIS

Syntax:

.SYNOPSIS

Beskrivning:

Det här direktivet tillåter en kort beskrivning av funktionen eller skriptet. (Direktivet .DESCRIPTION (·A.2.1) är avsett för en detaljerad beskrivning.) Det här direktivet kan bara användas en gång i varje ämne.

Exempel:

<#
.SYNOPSIS
Computes Base to the power Exponent.
#>