PowerShell スクリプトのコメントベースのヘルプを作成する

この記事では、スクリプトと関数のコメント ベースのヘルプ トピックを作成する方法を示します。 特別なヘルプ コメント キーワードを使用してトピックを作成します。

Get-Help コマンドレットを使用して、XML ファイルによって生成されるものと同様のコメント ベースのヘルプ トピックを表示します。

PowerShell のコメントベースのヘルプ

以下に、コメントベースのヘルプの構文を示します。

# .<help keyword>
# <help content>

また

<#
.<help keyword>
<help content>
#>

コメント ベースのヘルプ トピックは、一連のコメントとして記述します。 コメントをマークするには、各コメント行の先頭に # 記号を追加するか、<# と #> を使用してコメント ブロックを作成します。

コンソールは、コメント ブロック内の行をコメントとして登録します。

特別なキーワードを使用して、コメント ベースのトピック ヘルプの各セクションを定義します。 . で始まるキーワード 大文字と小文字は区別されません。

以下に例を示します。

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

上記の例では、.Description キーワードはコメントを関数の説明としてマークします。

コメント ブロックには少なくとも 1つのキーワードが必要です。 キーワードには 1 回しか表示されないものもあれば、制限がないものもあります。

キーワードのコンテンツは、キーワードの直後の行から開始する必要があり、制限はありません。

関数のコメントベースのヘルプを追加する場合、以下で説明する 3つの場所のいずれかに追加できます。

1. 関数本体の開始時。
2. 関数本体の最後。
3. function キーワードの前。 1 行以上の空白行で区切られていません。

例:

function Get-Function
{
<#
.<help keyword>
<content>
#>

  # function logic
}

また

function Get-Function
{
   # function logic

<#
.<help keyword>
<content>
#>
}

また

<#
.<help keyword>
<content>
#>
function Get-Function { }

スクリプトのコメントベースのヘルプは、スクリプトの最初または最後に表示できます。 ここではいくつかの例を示します。

<#
.<help keyword>
<content>
#>

function Get-Function { }

また

function Get-Function { }

<#
.<help keyword>
<content>
#>

PowerShell のコメント ベースのキーワード

以下に、有効なコメント ベースのヘルプ キーワードを示します。 これらは任意の順序で表示でき、大文字と小文字は区別されません。

.SYNOPSIS

これは、関数またはスクリプトの簡単な説明です。 キーワードは、各トピックに 1 回だけ表示する必要があります。

.DESCRIPTION

これは、関数またはスクリプトの詳細な説明です。 各トピックで一度だけ使用します。

.PARAMETER

これは、スクリプトまたは関数のパラメーターを記述します。 スクリプトまたは関数のすべてのパラメーターに .PARAMETER キーワードを追加します。

.PARAMETER <Parameter-Name>

パラメータ キーワードは、コメント ブロック内の厳密な順序に従っていません。 スクリプトまたは関数内のパラメーターの構文によって、ヘルプ トピック内の順序が決まります。

構文を変更することで順序を変更できます。

または関数またはスクリプトにコメントを追加することで、パラメータ キーワードの内容を指定できます。 このコメントは、パラメーター変数名の前に置く必要があります。

PowerShell は、パラメーター キーワードに関連付けられた説明を、両方が使用されている構文コメントよりも優先します。

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.EXAMPLE

スクリプトまたは関数を使用するサンプル コマンドを含めます。 スクリプトまたは関数のすべての例にこのキーワードを含めることができます。

.INPUTS

これらは、スクリプトまたは関数にパイプできる .NET オブジェクトです。 入力オブジェクトの説明を追加できます。

.OUTPUTS

これらは、コマンドレットが返す .NET オブジェクトです。 返されたオブジェクトの説明を追加できます。

.NOTES

これらは、スクリプトまたは関数に関する追加情報です。 情報には、コード化された日付、関数名、または作成者の名前を含めることができます。

.LINK

これらは関連トピックです。

関数のコメントベースのヘルプの例を次に示します。

結論として、コメント ブロックに配置することで、関数またはスクリプトにコメント ベースのヘルプを追加できます。 ヘルプ トピックを追加するときは、上記で説明したキーワードを使用し、スクリプトと関数のコメント ブロックを配置する場所を覚えておいてください。