Feedback

A. Comment-Based Help

  • Artikel
  • 5 minuten om te lezen

PowerShell biedt een mechanisme voor programmeurs om hun scripts te documenteren met behulp van speciale opmerkingen-instructies. Opmerkingen die gebruikmaken van een dergelijke syntaxis worden Help-opmerkingen genoemd. De cmdlet Get-Help genereert documentatie van deze instructies.

Inleiding tot A.1

Een Help-opmerking bevat een Help-richtlijn van het formulier . naam gevolgd op een of meer volgende regels door de tekst van de Help-inhoud. De Help-opmerking kan worden gemaakt uit een reeks opmerkingen met één regel of een commentaar met scheidingstekens (2.2.3). De set opmerkingen die bestaat uit de documentatie voor één entiteit wordt een Help-onderwerp genoemd.

Bijvoorbeeld:

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

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

of

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

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

Alle regels in een Help-onderwerp moeten aaneengesloten zijn. Als een Help-onderwerp een opmerking volgt die geen deel uitmaakt van dat onderwerp, moet er ten minste één lege regel tussen de twee staan.

De instructies kunnen in elke volgorde worden weergegeven en sommige instructies kunnen meerdere keren worden weergegeven.

Namen van de -richtlijnen zijn niet casegevoelig.

Wanneer u een functie documenteert, kunnen Help-onderwerpen worden weergegeven op een van de volgende drie locaties:

  • Direct vóór de functiedefinitie met niet meer dan één lege regel tussen de laatste regel van de functie help en de regel met de functie-instructie.
  • In de hoofdtitel van de functie direct na het haakje openen.
  • In de hoofdtitel van de functie direct vóór het haakje sluiten.

Wanneer u een scriptbestand documenteert, kunnen helponderwerpen worden weergegeven op een van de volgende twee locaties:

  • Aan het begin van het scriptbestand, eventueel voorafgegaan door opmerkingen en alleen lege regels. Als het eerste item in het script na de Help een functiedefinitie is, moeten er ten minste twee lege regels zijn tussen het einde van de Help van het script en die functiedeclaratie. Anders wordt de Help geïnterpreteerd als van toepassing op de functie in plaats van het scriptbestand.
  • Aan het einde van het scriptbestand.

A.2 Help-instructies

A.2.1 . BESCHRIJVING

Syntaxis:

.DESCRIPTION

Beschrijving:

Deze -instructies maken een gedetailleerde beschrijving van de functie of het script mogelijk. (De .SYNOPSIS -richtlijn (*A.2.11) is bedoeld voor een korte beschrijving.) Deze -richtlijn kan slechts één keer in elk onderwerp worden gebruikt.

Voorbeelden:

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

A.2.2 . VOORBEELD

Syntaxis:

.EXAMPLE

Beschrijving:

Met deze -opdracht kan een voorbeeld van opdrachtgebruik worden weergegeven.

Als deze -richtlijn meerdere keren optreedt, wordt elk bijbehorend Help-inhoudsblok weergegeven als een afzonderlijk voorbeeld.

Voorbeelden:

<#
.EXAMPLE
Get-Power 3 4
81

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

A.2.3 . EXTERNALHELP

Syntaxis:

.EXTERNALHELP <XMLHelpFilePath>

Beschrijving:

Met deze -richtlijn geeft u het pad op naar een helpbestand op basis van XML voor het script of de functie.

Hoewel help op basis van opmerkingen eenvoudiger te implementeren is, is help op basis van XML vereist als er meer nauwkeurige controle nodig is over Help-inhoud of als Help-onderwerpen moeten worden vertaald in meerdere talen. De details van de help op basis van XML worden niet gedefinieerd door deze specificatie.

Voorbeelden:

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

A.2.4 . FORWARDHELPCATEGORY

Syntaxis:

.FORWARDHELPCATEGORY <Category>

Beschrijving:

Specifies the help category of the item in ForwardHelpTargetName (§A.2.5). Geldige waarden zijn Alias, All, Cmdlet, ExternalScript, FAQ, Filter, Function, General, Glossary, HelpFile, Provider en ScriptCommand. Gebruik deze -richtlijn om conflicten te voorkomen wanneer er opdrachten met dezelfde naam zijn.

Voorbeelden:

Zie .A.2.5.

A.2.5 . FORWARDHELPTARGETNAME

Syntaxis:

.FORWARDHELPTARGETNAME <Command-Name>

Beschrijving:

Wordt omgeleid naar het Help-onderwerp dat is opgegeven door <Command-Name>.

Voorbeelden:

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

De opdracht Get-Help help wordt in plaats daarvan behandeld alsof het zo Get-Help Get-Help is.

A.2.6 . INGANGEN

Syntaxis:

.INPUTS

Beschrijving:

De pijplijn kan worden gebruikt om een of meer objecten door te susen naar een script of functie. Deze -richtlijn wordt gebruikt om dergelijke objecten en hun typen te beschrijven.

Als deze -instructies meerdere keren voorkomen, wordt elk bijbehorend Help-inhoudsblok verzameld in de ene documentatie-vermelding, in de lexicale volgorde van de -instructies.

Voorbeelden:

<#
.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,
        ...
    )
    ...
}

Syntaxis:

.LINK

Beschrijving:

Met deze -richtlijn geeft u de naam van een gerelateerd onderwerp op.

Als deze -instructies meerdere keren voorkomen, wordt elk bijbehorend Help-inhoudsblok verzameld in de ene documentatie-vermelding, in de lexicale volgorde van de -instructies.

De inhoud van de Koppelings-richtlijn kan ook een URI naar een onlineversie van hetzelfde Help-onderwerp bevatten. De onlineversie wordt geopend wanneer Get-Help wordt aangeroepen met de parameter Online. De URI moet beginnen met 'http' of 'https'.

Voorbeelden:

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

.LINK
Set-ProcedureName
#>

A.2.8 . NOTITIES

Syntaxis:

.NOTES

Beschrijving:

Met deze -richtlijn kan aanvullende informatie over de functie of het script worden opgegeven. Deze -richtlijn kan slechts één keer in elk onderwerp worden gebruikt.

Voorbeelden:

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

A.2.9 . UITGANGEN

Syntaxis:

.OUTPUTS

Beschrijving:

Deze -opdracht wordt gebruikt om de uitvoer van de objecten te beschrijven met een opdracht.

Als deze -instructies meerdere keren voorkomen, wordt elk bijbehorend Help-inhoudsblok verzameld in de ene documentatie-vermelding, in de lexicale volgorde van de -instructies.

Voorbeelden:

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

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

A.2.10 . PARAMETER

Syntaxis:

.PARAMETER <Parameter-Name>

Beschrijving:

Met deze -instructies kunt u een gedetailleerde beschrijving van de opgegeven parameter opgeven. Deze -richtlijn kan één keer worden gebruikt voor elke parameter. Parameter-instructies kunnen in elke volgorde worden weergegeven in het opmerkingenblok; De volgorde waarin de bijbehorende parameters daadwerkelijk worden gedefinieerd in de bron, bepaalt echter de volgorde waarin de parameters en de bijbehorende beschrijvingen worden weergegeven in de resulterende documentatie.

Een alternatieve indeling omvat het plaatsen van een opmerking met een parameterbeschrijving direct vóór de declaratie van de naam van de bijbehorende parametervariabele. Als de bron zowel een opmerking bij de beschrijving van de parameter als een Parameter-richtlijn bevat, wordt de beschrijving gebruikt die is gekoppeld aan de Parameter-richtlijn.

Voorbeelden:

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

Syntaxis:

.SYNOPSIS

Beschrijving:

Met deze -opdracht kunt u een korte beschrijving van de functie of het script geven. (De .DESCRIPTION -instructies (a.2.1) zijn bedoeld voor een gedetailleerde beschrijving.) Deze -richtlijn kan slechts één keer in elk onderwerp worden gebruikt.

Voorbeelden:

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