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

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

```powershell
Get-Help <自作の関数名>
```

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

### Windows PowerShell ISE を使用する

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

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

#### Cmdlet (高度な関数) - 完了

```powershell
<#
.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][]
- [コメントベースのヘルプの作成][]
- [高度な関数][]

[about_Comment_Based_Help]: <https://docs.microsoft.com/ja-jp/previous-versions/windows/powershell-scripting/hh847834(v=wps.640)?redirectedfrom=MSDN>
[コメントベースのヘルプの作成]: <http://suyamasoft.blue.coocan.jp/PowerShell/Tips/Comment_Based_Help/index.html>
[高度な関数]: <http://suyamasoft.blue.coocan.jp/PowerShell/Tips/CmdletBinding/index.html>