PowerShell　関数ドキュメンテーション

概要

PowerShellでは、
関数の使い方や注意点をコメントを使って
記録するための、書式が定められています（関数ドキュメンテーション）。
この記事では、基本的な要素を抜粋して紹介します。

開始タグと閉じタグ

<#がドキュメンテーション開始タグ、
#>がドキュメンテーション閉じタグです。

要素一覧

.SYNOPSIS

ユーザーが知りたい、関数の動作・用途の概略を示します。

.DESCRIPTION

.SYNOPSISで書ききれない詳細を書きます。
関数を使った時のメリット、対応する既存のやり方のデメリットも書くべきです。

.PARAMETER 引数名

各引数についての注釈を書きます

.INPUTS

パイプラインでの入力に関する注釈を書きます

.OUTPUTS

出力される戻り値について書きます

.EXAMPLE

使用例をかきます。
コマンドの入力と、出力結果の双方を書くべきです。

コード例

function Get-IndexValuePairs {  
    <#
    .SYNOPSIS
        この関数は、配列を渡すと、
        元の配列のインデックスと値がペアになった
        アイテムの配列を返します
    .DESCRIPTION
        この関数を使うと、以下のメリットを享受できます:
            1. 配列のインデックスを簡単に取得できる
            2. 毎回手作業でfor文を使ってインデックスを取らずに済む
            3. インデックスと値のペアをforeach文の中で利用できる
            
        換言すると、既存の手段の持つ、以下のデメリットを回避できます:
            1. 配列のインデックスを取得する関数、メソッド、プロパティがない
            2. 毎回for文を手書きすると、範囲外インデックスを指定する危険がある
            3. foreach文では簡便な手段でインデックスと値を使うことができない        
    .PARAMETER Items
        インデックスと値のペアを取得したい配列を入れます
    .INPUTS
        パイプラインでの入力に対応しています。
        パイプラインでの入力は、$Itemsの引数に渡されます
    .OUTPUTS
        自作型のIndexValuePairの配列を返します。
    .EXAMPLE 
        PS C:\Sample> Get-IndexValuePairs -Items "a", "b", "c"
        Index Value
        _____ _____
            0     a
            1     b
            2     c
    #>
    
    [OutputType([IndexValuePair[]])]
    [CmdletBinding()]
    param (
        [Parameter(ValueFromPipeLine)]
        [Object[]] $Items
    )
    
    begin{}    
    process{
        return $(
            for($index = 0; $index -lt $Items.Count; $index++){
                [IndexValuePair]::new($index, $Items[$index])
            }
        )
    }    
    end{}
}

呼び出し方

関数ドキュメンテーションを
実際に確認する時は、Get-Helpを使います。

Get-Help コマンド名
Get-Help 関数名 -Full

実行結果