【PowerShell】コマンドレットヘルプの記述

Get-Help コマンドレットを使用してヘルプメッセージとして表示される、関数コメントの記述方法です。

Get-Help <自作の関数名>

関数でコメントベースのヘルプを記載する場所は function の直前か、function の { の後、あるいは function の終わりの } の前に記載します。スクリプトのコメントベースのヘルプを記載する場所はファイルの最初か、最後です。

Windows PowerShell ISE を使用する

Windows PowerShell ISE のスニペットの機能を利用して、コマンドレットヘルプ付きの関数のテンプレートを挿入する方法です。

1. Windows PowerShell ISE で新規のスクリプトタブのテキストエディタ部分で右クリックをして、[スニペットの開始(S)] を選択します。
   
2. スニペットの一覧から「Cmdlet (高度な関数)」、または「Cmdlet (高度な関数) - 完了」を選択するとテンプレートを挿入します。
   

Cmdlet (高度な関数) - 完了

<#
.Synopsis
   短い説明
.DESCRIPTION
   詳しい説明
.EXAMPLE
   このコマンドレットの使用方法の例
.EXAMPLE
   このコマンドレットの使用方法の別の例
.INPUTS
   このコマンドレットへの入力 (存在する場合)
.OUTPUTS
   このコマンドレットからの出力 (存在する場合)
.NOTES
   全般的な注意
.COMPONENT
   このコマンドレットが属するコンポーネント
.ROLE
   このコマンドレットが属する役割
.FUNCTIONALITY
   このコマンドレットの機能
#>
function Verb-Noun
{
    [CmdletBinding(DefaultParameterSetName='Parameter Set 1', 
                  SupportsShouldProcess=$true, 
                  PositionalBinding=$false,
                  HelpUri = 'http://www.microsoft.com/',
                  ConfirmImpact='Medium')]
    [Alias()]
    [OutputType([String])]
    Param
    (
        # パラメーター 1 のヘルプの説明
        [Parameter(Mandatory=$true, 
                   ValueFromPipeline=$true,
                   ValueFromPipelineByPropertyName=$true, 
                   ValueFromRemainingArguments=$false, 
                   Position=0,
                   ParameterSetName='Parameter Set 1')]
        [ValidateNotNull()]
        [ValidateNotNullOrEmpty()]
        [ValidateCount(0,5)]
        [ValidateSet("sun", "moon", "earth")]
        [Alias("p1")] 
        $Param1,

        # パラメーター 2 のヘルプの説明
        [Parameter(ParameterSetName='Parameter Set 1')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [ValidateScript({$true})]
        [ValidateRange(0,5)]
        [int]
        $Param2,

        # パラメーター 3 のヘルプの説明
        [Parameter(ParameterSetName='Another Parameter Set')]
        [ValidatePattern("[a-z]*")]
        [ValidateLength(0,15)]
        [String]
        $Param3
    )

    Begin
    {
    }
    Process
    {
        if ($pscmdlet.ShouldProcess("Target", "Operation"))
        {
        }
    }
    End
    {
    }
}

コメントベースのヘルプのキーワード

代表的なキーワードの一覧です。※詳細は about_Comment_Based_Help を参照

キーワード	説明
.SYNOPSIS	関数またはスクリプトの簡単な概要。
.DESCRIPTION	関数またはスクリプトの詳細な説明。
.PARAMETER <パラメーター名>	パラメーターの説明。パラメーターの前のコメントよりもこちらが優先されます。
.EXAMPLE	関数またはスクリプトを使用するサンプル コマンド。必要に応じて、サンプル出力と説明を記述します(複数可)。例 1、例 2、例 3...
.INPUTS	パイプを使用して関数またはスクリプトに渡すことができるオブジェクトの Microsoft .NET Framework 型。入力オブジェクトの説明を含めることもできます。
.OUTPUTS	コマンドレットによって返されるオブジェクトの .NET Framework 型。返されるオブジェクトの説明を含めることもできます。
.NOTES	関数またはスクリプトに関する追加情報。
.LINK	関連するリンク トピック(コマンドレット名)、あるいはURI。

参考サイト

• about_Comment_Based_Help
• コメントベースのヘルプの作成
• 高度な関数