PowerShell => Pomoc oparta na komentarzach

Wprowadzenie

PowerShell zawiera mechanizm dokumentacji zwany pomocą opartą na komentarzach. Umożliwia dokumentowanie skryptów i funkcji za pomocą komentarzy do kodu. Pomoc oparta na komentarzach jest najczęściej zapisywana w blokach komentarzy zawierających wiele słów kluczowych pomocy. Słowa kluczowe pomocy zaczynają się od kropek i identyfikują sekcje pomocy, które zostaną wyświetlone po uruchomieniu polecenia cmdlet Get-Help .

Pomoc oparta na komentarzach funkcji

<#

.SYNOPSIS
    Gets the content of an INI file.

.DESCRIPTION
    Gets the content of an INI file and returns it as a hashtable.

.INPUTS
    System.String

.OUTPUTS
    System.Collections.Hashtable

.PARAMETER FilePath
    Specifies the path to the input INI file.

.EXAMPLE
    C:\PS>$IniContent = Get-IniContent -FilePath file.ini
    C:\PS>$IniContent['Section1'].Key1
    Gets the content of file.ini and access Key1 from Section1.

.LINK
    Out-IniFile

#>
function Get-IniContent
{
    [CmdletBinding()]
    Param
    (
        [Parameter(Mandatory=$true,ValueFromPipeline=$true)]
        [ValidateNotNullOrEmpty()]
        [ValidateScript({(Test-Path $_) -and ((Get-Item $_).Extension -eq ".ini")})]
        [System.String]$FilePath
    )

    # Initialize output hash table.
    $ini = @{}
    switch -regex -file $FilePath
    {
        "^\[(.+)\]$" # Section
        {
            $section = $matches[1]
            $ini[$section] = @{}
            $CommentCount = 0
        }
        "^(;.*)$" # Comment
        {
            if( !($section) )
            {
                $section = "No-Section"
                $ini[$section] = @{}
            }
            $value = $matches[1]
            $CommentCount = $CommentCount + 1
            $name = "Comment" + $CommentCount
            $ini[$section][$name] = $value
        } 
        "(.+?)\s*=\s*(.*)" # Key
        {
            if( !($section) )
            {
                $section = "No-Section"
                $ini[$section] = @{}
            }
            $name,$value = $matches[1..2]
            $ini[$section][$name] = $value
        }
    }
        
    return $ini
}

Powyższą dokumentację funkcji można wyświetlić, uruchamiając Get-Help -Name Get-IniContent -Full :

Zauważ, że słowa kluczowe oparte na komentarzach zaczynające się od . dopasuj sekcje wyników Get-Help .

Pomoc oparta na komentarzach skryptowych

<#

.SYNOPSIS
    Reads a CSV file and filters it.

.DESCRIPTION
    The ReadUsersCsv.ps1 script reads a CSV file and filters it on the 'UserName' column.

.PARAMETER Path
    Specifies the path of the CSV input file.

.INPUTS
    None. You cannot pipe objects to ReadUsersCsv.ps1.

.OUTPUTS
    None. ReadUsersCsv.ps1 does not generate any output.

.EXAMPLE
    C:\PS> .\ReadUsersCsv.ps1 -Path C:\Temp\Users.csv -UserName j.doe

#>
Param
(
    [Parameter(Mandatory=$true,ValueFromPipeline=$false)]
    [System.String]
    $Path,
    [Parameter(Mandatory=$true,ValueFromPipeline=$false)]
    [System.String]
    $UserName
)

Import-Csv -Path $Path | Where-Object -FilterScript {$_.UserName -eq $UserName}

Powyższą dokumentację skryptu można wyświetlić, uruchamiając Get-Help -Name ReadUsersCsv.ps1 -Full :

Modified text is an extract of the original Stack Overflow Documentation

Licencjonowany na podstawie CC BY-SA 3.0

Nie związany z Stack Overflow

PowerShell
Pomoc oparta na komentarzach

Szukaj…

Wprowadzenie

Pomoc oparta na komentarzach funkcji

Pomoc oparta na komentarzach skryptowych