トピック
    about_Comment_Based_Help

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

詳細説明
    特別なヘルプのコメント キーワードを使用して、関数およびスクリプトに関するコメントベースのヘ
    ルプ トピックを記述することができます。

    Get-Help コマンドレットでは、XML ファイルから生成されるコマンドレットのヘルプ トピックを表
    示する場合と同じ形式でコメントベースのヘルプが表示されます。ユーザーは、Get-Help の 
    Detailed、Full、Example、Online などのすべてのパラメーターを使用して、関数およびスクリ
    プトのヘルプを表示することができます。

    また、ヘルプのコメント キーワードを使用して、スクリプトおよび関数に関する XML ベースのヘル
    プ ファイルを記述したり、別のヘルプ ファイルにユーザーをリダイレクトすることもできます。

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


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

        # .< help keyword>
        # <help content>
 
    - または -

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


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

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

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

    たとえば、関数またはスクリプトの説明の前には、Description キーワードを記述します。

        <#
	    .Description
            Get-Function は、セッションにあるすべての関数の名前および構文を表示します。
        #>

    コメント ブロックには少なくとも 1 つのキーワードが含まれている必要があります。EXAMPLE な
    どの一部のキーワードは、同じコメント ブロックに何度も指定することができます。各キーワードの
    ヘルプの内容は、キーワードの次の行から開始して複数行に記述できます。



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

    関数に関するコメントベースのヘルプは、次に示す 3 つの位置のいずれかに指定することができます。

        -- 関数本体の先頭。

        -- 関数本体の末尾。

        -- Function キーワードの前。関数のヘルプの最終行と Function キーワードとの間に複数の
           空白行を挿入することはできません。

 

    次にその例を示します。

        function MyFunction
        {
            <#
            .< help keyword>
            < help content>
            #>

            <function commands>
        }


    - または -

        function MyFunction
        {
            <function commands>

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

    - または -

        <#
        .< help keyword>
        < help content>
        #>
        function MyFunction { }



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

    スクリプトに関するコメントベースのヘルプは、次に示すスクリプト内の 2 つの位置のいずれかに指
    定することができます。

    -- スクリプト ファイルの先頭。スクリプト内でスクリプトのヘルプより前に配置できるのは、コメ
       ントおよび空白行のみです。

    -- (ヘルプの後の) スクリプト本文の最初の項目が関数宣言である場合は、スクリプトのヘルプの末
       尾と関数宣言との間に、少なくとも 2 行の空白行が必要です。そうしないと、このヘルプがスク
       リプトに関するヘルプではなく、関数に関するヘルプとして解釈されます。

    -- スクリプト ファイルの末尾。



    次にその例を示します。

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


        function MyFunction { }

    - または -


        function MyFunction { }

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



 コメントベースのヘルプ キーワード
    有効なコメントベースのヘルプ キーワードを以下に示します。この一覧は、ヘルプ トピックでの
    一般的な出現順に、各キーワードの使用目的を説明しています。これらのキーワードは、コメント
    ベースのヘルプに任意の順序で記述することができます。大文字と小文字は区別されません。


    .SYNOPSIS
        関数またはスクリプトの簡単な説明です。このキーワードは、各トピックで 1 回のみ使用する
        ことができます。

    .DESCRIPTION
        関数またはスクリプトの詳細な説明です。このキーワードは、各トピックで 1 回のみ使用する
        ことができます。

    .PARAMETER <Parameter-Name>
        パラメーターの説明です。関数またはスクリプトの構文で、各パラメーターに対して Parameter 
        キーワードを入れることができます。

        Parameter キーワードは、コメント ブロック内で任意の順序で記述することができますが、
        パラメーター (およびその説明) がヘルプ トピックで表示される順序はその関数またはスクリプ
        トの構文によって決定されます。順序を変更するには、構文を変更します。
 
        また、関数またはスクリプトの構文で、パラメーター変数名の直前にコメントを配置することによって、
        パラメーターの説明を記述することもできます。構文のコメントと Parameter キーワードの両方を使用
        した場合、Parameter キーワードに関連付けられている説明が使用され、構文のコメントは無視されます。

    .EXAMPLE
        関数またはスクリプトを使用したサンプル コマンドです。オプションでサンプル出力および説
        明を記述します。それぞれの例に対してこのキーワードを記述します。

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

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

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

    .LINK
        関連トピックの名前です。それぞれの関連トピックに対してこのキーワードを記述します。

        この内容は、ヘルプ トピックの「関連するリンク」セクションに表示されます。

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

    .COMPONENT
        関数またはスクリプトで使用されているか、関数またはスクリプトに関連するテクノロジまたは
        機能です。この内容は、Get-Help コマンドに Get-Help の Component パラメーターが含まれ
        ている場合に表示されます。

    .ROLE
        ヘルプ トピックのユーザー ロールです。この内容は、Get-Help コマンドに Get-Help の 
        Role パラメーターが含まれている場合に表示されます。

    .FUNCTIONALITY
        関数の使用目的です。この内容は、Get-Help コマンドに Get-Help の Functionality パラメー
        ターが含まれている場合に表示されます。

    .FORWARDHELPTARGETNAME <Command-Name>
        指定されたコマンドのヘルプ トピックにリダイレクトします。関数、スクリプト、コマンド
        レット、プロバイダーに関するヘルプ トピックなど、任意のヘルプ トピックにユーザーをリ
        ダイレクトすることができます。

    .FORWARDHELPCATEGORY <Category>
        ForwardHelpTargetName 内の項目のヘルプ カテゴリを指定します。
        有効な値は、Alias、Cmdlet、HelpFile、Function、Provider、General、FAQ、Glossary、
        ScriptCommand、ExternalScript、Filter、または All です。このキーワードを使用して、
        同じ名前のコマンドがある場合の競合を回避します。

    .REMOTEHELPRUNSPACE <PSSession-variable>
        ヘルプ トピックが含まれているセッションを指定します。PSSession が含まれている変数を
        入力します。このキーワードは、エクスポートされたコマンドのヘルプ トピックを検索する
        ために、Export-PSSession コマンドレットによって使用されます。

    .EXTERNALHELP <XML Help File Path>
        スクリプトまたは関数に関する XML ベースのヘルプ ファイルのパスを指定します。

        Windows Vista およびそれ以降の Windows では、指定された XML ファイルのパスに UI カル
        チャ固有のサブディレクトリが含まれていると、Get-Help はそれらのサブディレクトリを再帰
        的に検索し、スクリプトまたは関数の名前を持つ XML ファイルを探します。これは、Windows 
        Vista で導入された言語のフォールバック基準に従って、すべての XML ベースのヘルプ トピッ
        クの場合と同じように行われます。

        コマンドレット ヘルプの XML ベースのヘルプ ファイル形式の詳細については、MSDN 
        (Microsoft Developer Network) ライブラリの「コマンドレット ヘルプの記述方法 (英語
        ページの可能性があります)」(https://go.microsoft.com/fwlink/?LinkID=123415) を参照
        してください。


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

        名前:
            関数のヘルプ トピックの「名前」セクションは、関数構文の関数名から取得されます。
            スクリプトのヘルプ トピックの名前は、スクリプト ファイル名から取得されます。名前
            または大文字と小文字の区別を変更するには、関数構文またはスクリプト ファイル名を
            変更します。
 
        構文:
            ヘルプ トピックの「構文」セクションは、関数またはスクリプトの構文から生成されます。
            ヘルプ トピックの構文にパラメーターの .NET Framework 型などの詳細を追加するには、
            構文に詳細を追加します。パラメーターの型を指定しない場合、"Object" 型が既定値とし
            て挿入されます。

        パラメーター一覧:
            ヘルプ トピックのパラメーター一覧は、関数またはスクリプトの構文と、Parameter キー
            ワードを使用して追加した説明から生成されます。関数パラメーターは、関数またはスクリ
            プトの構文に出現するのと同じ順序で、ヘルプ トピックの「パラメーター」セクションに
            表示されます。また、パラメーター名のスペルおよび大文字と小文字の区別も構文から取得
            され、Parameter キーワードによって指定されたパラメーター名の影響は受けません。

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

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

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



例

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

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

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

            <#
            .SYNOPSIS
            指定した名前にファイル名拡張子を追加します。

            .DESCRIPTION
            指定した名前にファイル名拡張子を追加します。ファイル名または拡張子に任意の文字列を
            指定できます。

            .PARAMETER Name
            ファイル名を指定します。

            .PARAMETER Extension
            拡張子を指定します。既定値は "Txt" です。

            .INPUTS
            なし。オブジェクトを Add-Extension にパイプすることはできません。

            .OUTPUTS
            System.String。Add-Extension は、拡張子の付いた文字列 (ファイル名) を返します。

            .EXAMPLE
            C:\PS> extension -name "File"
            File.txt

            .EXAMPLE
            C:\PS> extension -name "File" -extension "doc"
            File.doc

            .EXAMPLE
            C:\PS> extension "File" "doc"
            File.doc

            .LINK
            オンライン バージョン: http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
            }



        結果は次のとおりです。

        C:\PS> get-help add-extension -full

        名前
            Add-Extension
    
        概要
            指定した名前にファイル名拡張子を追加します。
    
        構文
            Add-Extension [[-Name] <String>] [[-Extension] <String>] 
            [<CommonParameters>]
    
        説明
            指定した名前にファイル名拡張子を追加します。ファイル名または拡張子に任意の文字列を
            指定できます。
    
        パラメーター
           -Name
               ファイル名を指定します。
        
               必須                         false
               位置                         0
               既定値                       
               パイプライン入力を許可する   false
               ワイルドカード文字を許可する 
        
           -Extension
               拡張子を指定します。既定値は "Txt" です。
        
               必須                         false
               位置                         1
               既定値                       
               パイプライン入力を許可する   false
               ワイルドカード文字を許可する 
        
            <CommonParameters>
               このコマンドレットは、共通パラメーターとして、Verbose、Debug、ErrorAction、
               ErrorVariable、WarningAction、WarningVariable、OutBuffer、および OutVariable 
               をサポートします。詳細については、「get-help about_commonparameters」と入力して
               ヘルプを参照してください。
    

        入力
            なし。オブジェクトを Add-Extension にパイプすることはできません。
    
        出力
            System.String。Add-Extension は、拡張子の付いた文字列 (ファイル名) を返します。
        
            -------------------------- 例 1 -------------------------- 
            C:\PS> extension -name "File"
            File.txt
    
            -------------------------- 例 2 -------------------------- 
            C:\PS> extension -name "File" -extension "doc"
            File.doc
    
            -------------------------- 例 3 -------------------------- 
            C:\PS> extension "File" "doc"
            File.doc
    
        関連するリンク
            オンライン バージョン: http://www.fabrikam.com/extension.html
            Set-Item



    例 2: 関数構文のパラメーターの説明

        この例は、関数構文にパラメーターの説明が挿入されている点を除き、前の例と同じです。
        この形式は、簡単な説明を記述する場合に最も便利です。


        function Add-Extension
        {
            param
            (
                [string]
                # ファイル名を指定します。
                $name,

                [string]
                # ファイル名拡張子を指定します。既定値は "Txt" です。
                $extension = "txt"
            )
            $name = $name + "."+ $extension
            $name
      
            <#
            .SYNOPSIS
            指定した名前にファイル名拡張子を追加します。

            .DESCRIPTION
            指定した名前にファイル名拡張子を追加します。ファイル名または拡張子に任意の文字列を指定できます。

            .INPUTS
            なし。オブジェクトを Add-Extension にパイプすることはできません。

            .OUTPUTS
            System.String。Add-Extension は、拡張子の付いた文字列 (ファイル名) を返します。

            .EXAMPLE
            C:\PS> extension -name "File"
            File.txt

            .EXAMPLE
            C:\PS> extension -name "File" -extension "doc"
            File.doc

            .EXAMPLE
            C:\PS> extension "File" "doc"
            File.doc
 
            .LINK
            オンライン バージョン: http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
        }




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

        次のサンプル スクリプトには、コメントベースのヘルプが含まれます。

        終わりの "#>" と Param ステートメントの間にある空白行に留意してください。Param ステー
        トメントを持たないスクリプトでは、ヘルプ トピックの最後のコメントと最初の関数宣言との
        間に少なくとも 2 行の空白行が必要です。それらの空白行がない場合、Get-Help はスクリプト
        ではなく関数にヘルプ トピックを関連付けます。

           <#
           .SYNOPSIS
           毎月のデータ更新を実行します。

           .DESCRIPTION
           Update-Month.ps1 スクリプトは、過去 1 か月に生成された新しいデータでレジストリを更新
           し、レポートを生成します。
    
           .PARAMETER InputPath
           CSV ベースの入力ファイルのパスを指定します。

           .PARAMETER OutputPath
           CSV ベースの出力ファイルの名前およびパスを指定します。既定では、MonthlyUpdates.ps1 
           は実行された日付と時刻から名前を生成し、ローカル ディレクトリに出力を保存します。

           .INPUTS
           なし。オブジェクトを Update-Month.ps1 にパイプすることはできません。

           .OUTPUTS
           なし。Update-Month.ps1 は出力を生成しません。

           .EXAMPLE
           C:\PS> .\Update-Month.ps1

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

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

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

           function Get-Data { }
           ...


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


            PS C:\ps-test> get-help .\update-month.ps1 -full

            名前
                C:\ps-test\Update-Month.ps1
    
            概要
                毎月のデータ更新を実行します。
    
            構文
                C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-
                OutputPath] <String>] [<CommonParameters>]
    
            説明
                Update-Month.ps1 スクリプトは、過去 1 か月に生成された新しいデータでレジスト
                リを更新し、レポートを生成します。
    
            パラメーター
               -InputPath
                   CSV ベースの入力ファイルのパスを指定します。
        
                   必須                         true
                   位置                         0
                   既定値                       
                   パイプライン入力を許可する   false
                   ワイルドカード文字を許可する 
        
               -OutputPath
                   CSV ベースの出力ファイルの名前およびパスを指定します。既定では、
                   MonthlyUpdates.ps1 は実行された日付と時刻から名前を生成し、ローカル ディレクト
                   リに出力を保存します。
        
                   必須                         false
                   位置                         1
                   既定値                       
                   パイプライン入力を許可する   false
                   ワイルドカード文字を許可する 

               <CommonParameters>
                   このコマンドレットは、共通パラメーターとして、Verbose、Debug、ErrorAction、
                   ErrorVariable、WarningAction、WarningVariable、OutBuffer、および OutVariable 
                   をサポートします。詳細については、「get-help about_commonparameters」と入力して
                   ヘルプを参照してください。
    
            入力
                   なし。オブジェクトを Update-Month.ps1 にパイプすることはできません。
    
            出力
                   なし。Update-Month.ps1 は出力を生成しません。
    
    
            -------------------------- 例 1 -------------------------- 
            C:\PS> .\Update-Month.ps1
    
            -------------------------- 例 2 -------------------------- 
            C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
    
            -------------------------- 例 3 -------------------------- 
            C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
            C:\Reports\2009\January.csv
        
            関連するリンク



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

        関数およびスクリプトに関する XML ベースのヘルプ トピックを記述することができます。コメ
        ントベースのヘルプは実装が簡単ですが、ヘルプの内容全体をより正確に制御する必要がある場
        合や、ヘルプ トピックを複数の言語に翻訳する場合は、XML ベースのヘルプが必要になります。

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


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


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

            function Get-Data { }
            ...



       次の例は、関数で ExternalHelp キーワードを使用する方法を示しています。


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


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

        次のコードは、Windows PowerShell の組み込み Help 関数の冒頭からの抜粋です。この関数は、
        一度に 1 画面ずつヘルプ テキストを表示します。Help 関数の説明は Get-Help コマンドレッ
        トのヘルプ トピックに含まれているため、Help 関数では、ForwardHelpTargetName と 
        ForwardHelpCategory の各キーワードを使用して、ユーザーを Get-Help コマンドレットのヘル
        プ トピックにリダイレクトします。

            function help
            {

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


        この機能は次のコマンドで使用されます。

            C:\PS> get-help help

            名前
                Get-Help

            概要
                Windows PowerShell のコマンドレットと概念に関する情報を表示します。
            ...


関連項目
    about_Functions
    about_Functions_Advanced_Parameters
    about_Scripts
    「コマンドレット ヘルプの記述方法 (英語ページの可能性があります)」
    (https://go.microsoft.com/fwlink/?LinkID=123415)






目次