about_Comment_Based_Help

[アーティクル]
10/04/2023

簡単な説明

関数とスクリプトのコメントベースのヘルプトピックを記述する方法について説明します。

詳細な説明

特別なヘルプコメントキーワード (keyword)を使用して、関数とスクリプトのコメントベースのヘルプトピックを記述できます。

Get-Help コマンドレットは、XML ファイルから生成されたコマンドレットのヘルプトピックを表示するのと同じ形式でコメントベースのヘルプを表示します。ユーザーは、詳細、完全、例、オンラインなどのすべてのパラメーターGet-Helpを使用して、コメントベースのヘルプの内容を表示できます。

関数やスクリプト用の XML ベースのヘルプファイルを記述することもできます。コマンドレットがGet-Help関数またはスクリプトの XML ベースのヘルプファイルを検索できるようにするには、キーワード (keyword)を.ExternalHelp使用します。このキーワード (keyword)がないと、Get-Help関数またはスクリプトの XML ベースのヘルプトピックが見つかりません。

このトピックでは、関数とスクリプトのヘルプトピックを記述する方法について説明します。関数とスクリプトのヘルプトピックを表示する方法については、「Get-Help」を参照してください。

Update-Help コマンドレットと Save-Help コマンドレットは、XML ファイルでのみ機能します。更新可能なヘルプでは、コメントベースのヘルプトピックはサポートされていません。

コメントベースのヘルプの構文

コメントベースのヘルプの構文は次のとおりです。

# .<help keyword>
# <help content>

または

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

コメントベースのヘルプは、一連のコメントとして書かれています。コメントの各行の前にコメント記号#を入力することも、記号と#>記号を<#使用してコメントブロックを作成することもできます。コメントブロック内のすべての行はコメントとして解釈されます。

コメントベースのヘルプトピックのすべての行は連続している必要があります。コメントベースのヘルプトピックが、ヘルプトピックの一部ではないコメントの後に続く場合は、最後の非ヘルプコメント行とコメントベースのヘルプの先頭の間に少なくとも 1 つの空白行が必要です。

キーワードは、コメントベースのヘルプの各セクションを定義します。各コメントベースのヘルプキーワード (keyword)の前にドットが付けられます.。キーワード (keyword)は任意の順序で表示できます。キーワード (keyword)名では大文字と小文字は区別されません。

たとえば、.Descriptionキーワード (keyword)は、関数またはスクリプトの説明の前に置きます。

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>

コメントブロックには、少なくとも 1 つのキーワード (keyword)が含まれている必要があります。たとえば.EXAMPLE、一部のキーワード (keyword)は、同じコメントブロックに何度も表示されることがあります。各キーワード (keyword)のヘルプコンテンツは、キーワード (keyword)の後の行から始まり、複数の行にまたがることができます。

関数でのコメントベースのヘルプの構文

関数のコメントベースのヘルプは、次の 3 つの場所のいずれかに表示できます。

関数本体の先頭。
関数本体の末尾。
キーワード (keyword)のfunction前。関数ヘルプの最後の行とキーワード (keyword)の間に複数の空白行をfunction指定することはできません。

次に例を示します。

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

  # function logic
}

function Get-Function
{
   # function logic

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

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

スクリプトでのコメントベースのヘルプの構文

スクリプトのコメントベースのヘルプは、スクリプト内の次の 2 つの場所のいずれかに表示できます。

スクリプトファイルの先頭。スクリプトのヘルプの前には、コメントと空白行のみを指定できます。

スクリプト本体の最初の項目 (ヘルプの後) が関数宣言である場合は、スクリプトヘルプの末尾と関数宣言の間に少なくとも 2 つの空白行が必要です。それ以外の場合、ヘルプは、スクリプトのヘルプではなく、関数のヘルプとして解釈されます。
スクリプトファイルの末尾。ただし、スクリプトが署名されている場合は、スクリプトファイルの先頭にコメントベースのヘルプを配置します。スクリプトの末尾は、署名ブロックによって占有されます。

次に例を示します。

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


function Get-Function { }

または

function Get-Function { }

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

スクリプトモジュールでのコメントベースのヘルプの構文

スクリプトモジュール .psm1では、コメントベースのヘルプでは、スクリプトの構文ではなく、関数の構文が使用されます。スクリプト構文を使用して、スクリプトモジュールで定義されているすべての関数のヘルプを提供することはできません。

たとえば、キーワード (keyword)を.ExternalHelp使用してスクリプトモジュール内の関数の XML ベースのヘルプファイルを識別する場合は、各関数にコメントを.ExternalHelp追加する必要があります。

# .ExternalHelp <XML-file-name>
function <function-name>
{
  ...
}

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

有効なコメントベースのヘルプキーワード (keyword)を次に示します。これらは、通常、ヘルプトピックに表示される順序で、目的の用途と共に一覧表示されます。これらのキーワード (keyword)はコメントベースのヘルプで任意の順序で表示でき、大文字と小文字は区別されません。

.SYNOPSIS

関数またはスクリプトの簡単な説明。このキーワード (keyword)は、各トピックで 1 回だけ使用できます。

.DESCRIPTION

関数またはスクリプトの詳細な説明。このキーワード (keyword)は、各トピックで 1 回だけ使用できます。

.PARAMETER

パラメーターの説明。 .PARAMETER 関数またはスクリプト構文の各パラメーターにキーワード (keyword)を追加します。

キーワード (keyword)と同じ行にパラメーター名を.PARAMETER入力します。キーワード (keyword)の後の行にパラメーターの説明を.PARAMETER入力します。 Windows PowerShell では、行と次の.PARAMETERキーワード (keyword)またはコメントブロックの末尾の間のすべてのテキストが、パラメーターの説明の一部として解釈されます。説明には、段落区切りを含めることができます。

.PARAMETER  <Parameter-Name>

Parameter キーワード (keyword)はコメントブロック内の任意の順序で表示できますが、関数またはスクリプトの構文によって、ヘルプトピックにパラメーター (およびその説明) が表示される順序が決まります。順序を変更するには、構文を変更します。

パラメーター変数名の直前に関数またはスクリプト構文にコメントを配置して、パラメーターの説明を指定することもできます。これを機能させるには、少なくとも 1 つのキーワード (keyword)を含むコメントブロックも必要です。

構文コメントとキーワード (keyword)の両方を.PARAMETER使用する場合、キーワード (keyword)に.PARAMETER関連付けられている説明が使用され、構文コメントは無視されます。

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .Parameter
        [string]$Computername
    )
    # Verb the Noun on the computer
}

.EXAMPLE

関数またはスクリプトを使用するサンプルコマンド。必要に応じて、サンプル出力と説明が続きます。各例について、このキーワード (keyword)を繰り返します。

.INPUTS

関数またはスクリプトにパイプ処理できる .NET 型のオブジェクト。入力オブジェクトの説明を含めることもできます。

.OUTPUTS

コマンドレットが返すオブジェクトの .NET 型。返されるオブジェクトの説明を含めることもできます。

.NOTES

関数またはスクリプトに関する追加情報。

.LINK

関連トピックの名前。値は ".LINK" キーワード (keyword)の下の行に表示され、コメント記号#の前に付けるか、コメントブロックに含まれている必要があります。

関連する.LINKトピックごとにキーワード (keyword)を繰り返します。

このコンテンツは、ヘルプトピックの [関連リンク] セクションに表示されます。

キーワード (keyword)コンテンツには.Link、同じヘルプトピックのオンラインバージョンへの URI (Uniform Resource Identifier) を含めることもできます。 Online パラメーターGet-Helpを使用すると、オンライン バージョンが開きます。 URI は先頭に "http" または "https" を付ける必要があります。

.COMPONENT

関数またはスクリプトが使用するテクノロジまたは機能の名前、または関連するテクノロジまたは機能の名前。の Component パラメーター Get-Help は、この値を使用して返される検索結果をフィルター処理します Get-Help。

.ROLE

ヘルプトピックのユーザーロールの名前。 Role パラメーターは、この値を使用して返される検索結果をフィルター処理しますGet-Help。Get-Help

.FUNCTIONALITY

関数の使用目的を説明するキーワード (keyword)。の Functionality パラメーター Get-Help は、この値を使用して、返される検索結果をフィルター処理します Get-Help。

.FORWARDHELPTARGETNAME

指定したコマンドのヘルプトピックにリダイレクトします。ユーザーは、関数、スクリプト、コマンドレット、プロバイダーのヘルプトピックなど、任意のヘルプトピックにリダイレクトできます。

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

の項目のヘルプカテゴリを指定します .ForwardHelpTargetName。有効な値はAlias、 , Cmdlet, , HelpFile, Function, Provider, General, FAQ, GlossaryScriptCommand, , ExternalScript, , Filterまたは All. 同じ名前のコマンドがある場合に競合を回避するには、このキーワード (keyword)を使用します。

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

ヘルプトピックを含むセッションを指定します。 PSSession オブジェクトを含む変数を入力します。このキーワード (keyword)は、エクスポートされたコマンドのヘルプトピックを検索するために Export-PSSession コマンドレットによって使用されます。

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

スクリプトまたは関数の XML ベースのヘルプファイルを指定します。

# .EXTERNALHELP <XML Help File>

.ExternalHelp 関数またはスクリプトが XML ファイルに記述されている場合は、キーワード (keyword)が必要です。このキーワード (keyword)がないと、Get-Help関数またはスクリプトの XML ベースのヘルプファイルが見つかりません。

キーワード (keyword)は.ExternalHelp、他のコメントベースのヘルプキーワード (keyword)よりも優先されます。存在する場合.ExternalHelpは、Get-Helpキーワード (keyword)の値と一致するヘルプトピックが見つからない場合でも、コメントベースの.ExternalHelpヘルプは表示されません。

関数がモジュールによってエクスポートされる場合は、パスのないファイル名に.ExternalHelpキーワード (keyword)の値を設定します。 Get-Help は、モジュールディレクトリの言語固有のサブディレクトリで、指定されたファイル名を検索します。関数の XML ベースのヘルプファイルの名前には要件はありませんが、次の形式を使用することをお勧めします。

<ScriptModule.psm1>-help.xml

関数がモジュールに含まれていない場合は、XML ベースのヘルプファイルへのパスを含めます。値にパスが含まれ、パスに UI カルチャ固有のサブディレクトリが含まれている場合は、 Get-Help モジュールディレクトリと同様に、Windows 用に確立された言語フォールバック標準に従って、スクリプトまたは関数の名前を持つ XML ファイルを再帰的に検索します。

コマンドレットヘルプの XML ベースのヘルプファイル形式の詳細については、「コマンドレットヘルプを記述する方法」を参照してください。

自動生成されたコンテンツ

名前、構文、パラメーターリスト、パラメーター属性テーブル、共通パラメーター、および注釈は、コマンドレットによって自動的に Get-Help 生成されます。

名前

関数ヘルプトピックの Name セクションは、関数構文の関数名から取得されます。スクリプトヘルプ トピックの名前 は、スクリプトファイル名から取得されます。名前またはその大文字を変更するには、関数の構文またはスクリプトファイル名を変更します。

構文

ヘルプトピックの構文セクションは、関数またはスクリプトの構文から生成されます。パラメーターの .NET 型など、ヘルプトピックの構文に詳細を追加するには、構文に詳細を追加します。パラメーター型を指定しない場合は、 既定値としてオブジェクト 型が挿入されます。

パラメーターリスト

ヘルプトピックのパラメーターリストは、関数またはスクリプトの構文と、キーワード (keyword)を使用して.Parameter追加した説明から生成されます。関数パラメーター は、ヘルプトピックの Parameters セクションに、関数またはスクリプト構文に表示される順序と同じ順序で表示されます。パラメーター名のスペルと大文字も構文から取得されます。キーワード (keyword)で指定されたパラメーター名の影響を.Parameter受けません。

共通パラメーター

共通パラメーターは、効果がない場合でも、ヘルプトピックの構文とパラメーターの一覧に追加されます。共通パラメーターの詳細については、about_CommonParametersを参照してください。

パラメーター属性テーブル

Get-Helpでは、Full パラメーターまたは Parameter パラメーターを使用するときに表示されるパラメーター属性のGet-Helpテーブルが生成されます。 Required 属性、Position 属性、および Default 値属性の値は、関数またはスクリプト構文から取得されます。

既定値と Accept Wildカード文字の値は、関数またはスクリプトで定義されている場合でも、パラメーター属性テーブルには表示されません。ユーザーを支援するには、パラメーターの説明でこの情報を指定します。

解説

ヘルプトピックの「解説」セクションは、関数名またはスクリプト名から自動的に生成されます。コンテンツを変更したり、その内容に影響を与えたりすることはできません。

例

関数のコメントベースのヘルプ

次のサンプル関数には、コメントベースのヘルプが含まれています。

function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. "Txt" is the default.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

結果は次のとおりです。

Get-Help -Name "Add-Extension" -Full

NAME

Add-Extension

SYNOPSIS

Adds a file name extension to a supplied name.

SYNTAX

Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]

DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

PARAMETERS

-Name
Specifies the file name.

Required?                    false
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-Extension
Specifies the extension. "Txt" is the default.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".

INPUTS
None. You cannot pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

関数構文でのパラメーターの説明

この例は前の例と同じですが、パラメーターの説明が関数構文に挿入される点が異なります。この形式は、説明が簡潔な場合に最も役立ちます。

function Add-Extension
{
param
(

[string]
#Specifies the file name.
$name,

[string]
#Specifies the file name extension. "Txt" is the default.
$extension = "txt"
)

$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

スクリプトのコメントベースのヘルプ

次のサンプルスクリプトには、コメントベースのヘルプが含まれています。終了 #> とステートメントの間の空白行に Param 注目してください。ステートメントがない Param スクリプトでは、ヘルプトピックの最後のコメントと最初の関数宣言の間に少なくとも 2 行の空白行が必要です。これらの空白行がない場合は、 Get-Help スクリプトではなく、ヘルプトピックを関数に関連付けます。

<#
.SYNOPSIS

Performs monthly data updates.

.DESCRIPTION

The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.

.INPUTS

None. You cannot pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 does not generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutPutPath)

function Get-Data { }
...

次のコマンドは、スクリプトのヘルプを取得します。スクリプトは環境変数にリスト $env:Path されているディレクトリ内にないため、 Get-Help スクリプトヘルプを取得するコマンドでスクリプトパスを指定する必要があります。

Get-Help -Name .\update-month.ps1 -Full

# NAME

C:\ps-test\Update-Month.ps1

# SYNOPSIS

Performs monthly data updates.

# SYNTAX

C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]

# DESCRIPTION

The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.

# PARAMETERS

-InputPath
Specifies the path to the CSV-based input file.

Required?                    true
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".

# INPUTS

None. You cannot pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 does not generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv

# RELATED LINKS

XML ファイルへのリダイレクト

関数とスクリプトの XML ベースのヘルプトピックを記述できます。コメントベースのヘルプを実装する方が簡単ですが、更新可能なヘルプと複数の言語でヘルプトピックを提供するには、XML ベースのヘルプが必要です。

次の例は、Update-Month.ps1 スクリプトの最初の数行を示しています。スクリプトでは、キーワード (keyword)を.ExternalHelp使用して、スクリプトの XML ベースのヘルプトピックへのパスを指定します。

キーワード (keyword)の.ExternalHelp値は、キーワード (keyword)と同じ行に表示されることに注意してください。その他の配置は無効です。

# .ExternalHelp C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...

次の例は、関数内のキーワード (keyword)の .ExternalHelp 3 つの有効な配置を示しています。

function Add-Extension
{
# .ExternalHelp C:\ps-test\Add-Extension.xml

param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name

# .ExternalHelp C:\ps-test\Add-Extension.xml
}

# .ExternalHelp C:\ps-test\Add-Extension.xml
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

別のヘルプトピックへのリダイレクト

次のコードは、PowerShell の組み込みヘルプ関数の先頭からの抜粋であり、一度に 1 つのヘルプテキスト画面が表示されます。コマンドレットのヘルプトピックGet-Helpにはヘルプ関数が記述されているため、ヘルプ関数は、ユーザーを.ForwardHelpTargetName.ForwardHelpCategory コマンドレットのヘルプトピックにリダイレクトGet-Helpするために、キーワード (keyword)を使用します。

function help
{

<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...

次のコマンドでは、この機能を使用します。

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

about_Comment_Based_Help

簡単な説明

詳細な説明

コメントベースのヘルプの構文

関数でのコメントベースのヘルプの構文

スクリプトでのコメントベースのヘルプの構文

スクリプトモジュールでのコメントベースのヘルプの構文

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

.SYNOPSIS

.DESCRIPTION

.PARAMETER

.EXAMPLE

.INPUTS

.OUTPUTS

.NOTES

.LINK

.COMPONENT

.ROLE

.FUNCTIONALITY

.FORWARDHELPTARGETNAME

.FORWARDHELPCATEGORY

.REMOTEHELPRUNSPACE

.EXTERNALHELP

自動生成されたコンテンツ

名前

構文

パラメーターリスト

共通パラメーター

パラメーター属性テーブル

解説

例

関数のコメントベースのヘルプ

関数構文でのパラメーターの説明

スクリプトのコメントベースのヘルプ

XML ファイルへのリダイレクト

別のヘルプトピックへのリダイレクト

関連項目

フィードバック

その他のリソース

about_Comment_Based_Help

簡単な説明

詳細な説明

コメントベースのヘルプの構文

関数でのコメント ベースのヘルプの構文

スクリプトでのコメント ベースのヘルプの構文

スクリプト モジュールでのコメント ベースのヘルプの構文

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

.SYNOPSIS

.DESCRIPTION

.PARAMETER

.EXAMPLE

.INPUTS

.OUTPUTS

.NOTES

.LINK

.COMPONENT

.ROLE

.FUNCTIONALITY

.FORWARDHELPTARGETNAME

.FORWARDHELPCATEGORY

.REMOTEHELPRUNSPACE

.EXTERNALHELP

自動生成されたコンテンツ

名前

構文

パラメーター リスト

共通パラメーター

パラメーター属性テーブル

解説

例

関数のコメント ベースのヘルプ

関数構文でのパラメーターの説明

スクリプトのコメントベースのヘルプ

XML ファイルへのリダイレクト

別のヘルプ トピックへのリダイレクト

関連項目

フィードバック

その他のリソース

関数でのコメントベースのヘルプの構文

スクリプトでのコメントベースのヘルプの構文

スクリプトモジュールでのコメントベースのヘルプの構文

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

パラメーターリスト

関数のコメントベースのヘルプ

別のヘルプトピックへのリダイレクト