Bagikan melalui

A. Bantuan Berbasis Komentar

Catatan editorial

Penting

Windows PowerShell Language Specification 3.0 diterbitkan pada Desember 2012 dan didasarkan pada Windows PowerShell 3.0. Spesifikasi ini tidak mencerminkan status PowerShell saat ini. Tidak ada rencana untuk memperbarui dokumentasi ini untuk mencerminkan status saat ini. Dokumentasi ini disajikan di sini untuk referensi historis.

Dokumen spesifikasi tersedia sebagai dokumen Microsoft Word dari Pusat Unduhan Microsoft di: https://www.microsoft.com/download/details.aspx?id=36389 Dokumen Word telah dikonversi untuk presentasi di sini di Microsoft Learn. Selama konversi, beberapa perubahan editorial telah dilakukan untuk mengakomodasi pemformatan untuk platform Dokumen. Beberapa kesalahan ketik dan kesalahan kecil telah dikoreksi.

PowerShell menyediakan mekanisme bagi programmer untuk mendokumentasikan skrip mereka menggunakan arahan komentar khusus. Komentar yang menggunakan sintaksis tersebut disebut komentar bantuan. Cmdlet Get-Help menghasilkan dokumentasi dari arahan ini.

Pengantar A.1

Komentar bantuan berisi direktif bantuan dalam format .nama diikuti pada satu atau beberapa baris berikutnya oleh teks konten bantuan. Komentar bantuan dapat terdiri dari serangkaian komentar baris tunggalatau komentar yang dibatasi (§2.2.3). Kumpulan komentar yang terdiri dari dokumentasi untuk satu entitas disebut topik bantuan .

Misalnya

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

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

atau

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

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

Semua baris dalam topik bantuan harus berturut-turut. Jika topik bantuan mengikuti komentar yang bukan bagian dari topik tersebut, setidaknya harus ada satu baris kosong di antara keduanya.

Direktif dapat muncul dalam urutan apa pun, dan beberapa direktif mungkin muncul beberapa kali.

Nama arahan tidak membedakan huruf besar/kecil.

Saat mendokumentasikan fungsi, topik bantuan mungkin muncul di salah satu dari tiga lokasi:

  • Segera sebelum definisi fungsi dengan tidak lebih dari satu baris kosong antara baris terakhir bantuan fungsi dan baris yang berisi pernyataan fungsi.
  • Di dalam isi fungsi segera setelah kurung kurawal yang dibuka.
  • Dalam badan fungsi tepat sebelum kurung kurawal penutupan.

Saat mendokumentasikan file skrip, topik bantuan mungkin muncul di salah satu dari dua lokasi:

  • Di awal file skrip, secara opsional didahului oleh komentar dan baris kosong saja. Jika item pertama dalam skrip setelah bantuan adalah definisi fungsi, setidaknya harus ada dua baris kosong antara akhir bantuan skrip dan deklarasi fungsi tersebut. Jika tidak, bantuan akan ditafsirkan sebagai diterapkan ke fungsi alih-alih file skrip.
  • Di akhir file skrip.

A.2 Petunjuk Bantuan

A.2.1 . DESKRIPSI

Sintaksis:

.DESCRIPTION

Deskripsi:

Arahan ini memungkinkan deskripsi terperinci tentang fungsi atau skrip. (Arahan .SYNOPSIS (§A.2.11) ditujukan untuk deskripsi singkat.) Arahan ini hanya dapat digunakan sekali di setiap topik.

Contoh:

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

A.2.2 . CONTOH

Sintaksis:

.EXAMPLE

Deskripsi:

Arahan ini memungkinkan contoh penggunaan perintah ditampilkan.

Jika arahan ini terjadi beberapa kali, setiap blok konten bantuan terkait ditampilkan sebagai contoh terpisah.

Contoh:

<#
.EXAMPLE
Get-Power 3 4
81

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

A.2.3 . EXTERNALHELP

Sintaksis:

.EXTERNALHELP <XMLHelpFilePath>

Deskripsi:

Direktif ini menentukan jalur ke file bantuan berbasis XML untuk skrip atau fungsi.

Meskipun bantuan berbasis komentar lebih mudah diterapkan, Bantuan berbasis XML diperlukan jika kontrol yang lebih tepat diperlukan atas konten bantuan atau jika topik bantuan akan diterjemahkan ke dalam beberapa bahasa. Detail bantuan berbasis XML tidak ditentukan oleh spesifikasi ini.

Contoh:

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

A.2.4 . KATEGORIBANTUANTERUSKAN

Sintaksis:

.FORWARDHELPCATEGORY <Category>

Deskripsi:

Menentukan kategori bantuan untuk item di ForwardHelpTargetName (§A.2.5). Nilai yang valid adalah Alias, Semua, Cmdlet, ExternalScript, FAQ, Filter, Fungsi, Umum, Glosarium, HelpFile, Penyedia, dan ScriptCommand. Gunakan direktif ini untuk menghindari konflik ketika ada perintah dengan nama yang sama.

Contoh:

Lihat §A.2.5.

A.2.5 . FORWARDHELPTARGETNAME

Sintaksis:

.FORWARDHELPTARGETNAME <Command-Name>

Deskripsi:

Mengalihkan ke topik bantuan yang ditentukan oleh <Command-Name>.

Contoh:

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

Perintah Get-Help help diperlakukan seolah-olah Get-Help Get-Help.

A.2.6 . INPUTS

Sintaksis:

.INPUTS

Deskripsi:

Alur dapat digunakan untuk menyalurkan satu atau beberapa objek ke skrip atau fungsi. Arahan ini digunakan untuk menggambarkan objek tersebut dan jenisnya.

Jika arahan ini terjadi beberapa kali, setiap blok konten bantuan terkait dikumpulkan dalam satu entri dokumentasi, dalam urutan leksikal arahan.

Contoh:

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

Sintaksis:

.LINK

Deskripsi:

Direktif ini menentukan nama topik terkait.

Jika arahan ini terjadi beberapa kali, setiap blok konten bantuan terkait dikumpulkan dalam satu entri dokumentasi, dalam urutan leksikal arahan.

Konten direktif Link juga dapat menyertakan URI untuk versi online topik bantuan yang sama. Versi online terbuka ketika Get-Help dipanggil dengan parameter Online. URI harus dimulai dengan "http" atau "https".

Contoh:

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

.LINK
Set-ProcedureName
#>

A.2.8 . CATATAN

Sintaksis:

.NOTES

Deskripsi:

Arahan ini memungkinkan informasi tambahan tentang fungsi atau skrip disediakan. Arahan ini hanya dapat digunakan sekali di setiap topik.

Contoh:

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

A.2.9 . KELUARAN

Sintaksis:

.OUTPUTS

Deskripsi:

Direktif ini digunakan untuk menjelaskan objek yang dihasilkan oleh perintah.

Jika arahan ini terjadi beberapa kali, setiap blok konten bantuan terkait dikumpulkan dalam satu entri dokumentasi, dalam urutan leksikal arahan.

Contoh:

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

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

A.2.10 . PARAMETER

Sintaksis:

.PARAMETER <Parameter-Name>

Deskripsi:

Arahan ini memungkinkan deskripsi terperinci tentang parameter yang diberikan. Arahan ini dapat digunakan sekali untuk setiap parameter. Direktif parameter dapat muncul dalam urutan apa pun di blok komentar; namun, urutan di mana parameter yang sesuai benar-benar didefinisikan dalam sumber menentukan urutan parameter dan deskripsinya muncul dalam dokumentasi yang dihasilkan.

Format alternatif melibatkan penempatan komentar deskripsi parameter segera sebelum deklarasi nama variabel parameter yang sesuai. Jika sumber berisi komentar deskripsi parameter dan direktif Parameter, deskripsi yang terkait dengan direktif Parameter digunakan.

Contoh:

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

Sintaksis:

.SYNOPSIS

Deskripsi:

Arahan ini memungkinkan deskripsi singkat tentang fungsi atau skrip. (Arahan .DESCRIPTION (§A.2.1) ditujukan untuk deskripsi terperinci.) Arahan ini hanya dapat digunakan sekali di setiap topik.

Contoh:

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