HOME > PowerShell > Tips > コメントベースのヘルプの作成

コメントベースのヘルプの作成


作成日 2017年09月12日
更新日 2018年03月13日

関数とスクリプトのヘルプを作成します。
コメントの中にドット(.)記号で始まるキーワードと、次の行以降がヘルプの内容になります。(行頭のスペースは削除されます)

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

Windows PowerShell ISEはコメントベースのヘルプを含むテンプレートを入力できます。
スクリプトウィンドウを右クリックして「スニペットの開始」メニューを実行します。あるいはCTRLキーを押しながら、Jキーを押します。
右クリックメニュー

「Cmdlet (高度な関数)」か「Cmdlet (高度な関数) - 完了」を選択するとテンプレートを挿入します。
右クリックメニュー
パラメーター用のヘルプは「.PARAMETER」キーワードではなく、各パラメーターの前に「# パラメーター 1 のヘルプの説明」などが挿入されます。パラメーターの前に記載しても良いが、優先順位は低いです。

コメントベースのヘルプのキーワード
キーワード説明
.SYNOPSIS概要 簡単な説明です。
.DESCRIPTION説明 詳細な説明です。
.PARAMETER パラメーター名パラメーター(複数可)。パラメーターの前のコメントよりもこちらが優先します。
.EXAMPLE例 1、例 2、例 3...(複数可)
.INPUTS入力
.OUTPUTS出力
.NOTESメモ (なぜかメモの後に2行改行してから表示します)
.LINK関連するリンク トピック(コマンドレット名)、あるいはURI
.EXTERNALHELP XMLのファイル名XMLベースのヘルプファイルを指定します。(自動更新や複数の言語で提供する場合)
.EXTERNALHELPを使用すると他のキーワードは無視します。
マイクロソフトのHow to Create the Cmdlet Help Fileを参照してください。
キーワードは指定されたコマンドレットのヘルプを表示する「.FORWARDHELPTARGETNAME」、同じコマンド名を区別するための「.FORWARDHELPCATEGORY」、ヘルプが含まれるセッションを指定する「.REMOTEHELPRUNSPACE」もあります。
キーワードの「.COMPONENT」、「.ROLE」、「.FUNCTIONALITY」は分かりませんでした。
【外部リンク】マイクロソフトのabout_Comment_Based_Helpを参照してください。

このページの上

下記は関数のコメントベースのヘルプの例です。
Function Add-Number
{
<#
.SYNOPSIS
 各行の左側に行番号を付けて表示します。

.DESCRIPTION
 各行の左側に指定した書式の行番号を付けて表示します。

.PARAMETER Lines
 複数の行の文字列です。

.PARAMETER NumberFormat
 行の番号の表示形式です。
 スペースが含まれる場合は、二重引用符(")で囲んでください。

.EXAMPLE
 Get-ChildItem *.txt | Add-Number
 00001: C:\bin\PowerShell\Sample\a.txt
 00002: C:\bin\PowerShell\Sample\b.txt

.EXAMPLE
 Add-Number -Lines ("a.txt", "b.txt") -NumberFormat "[00] "
 [01] a.txt
 [02] b.txt

.INPUTS
 複数行のテキストです。

.OUTPUTS
 各行に行番号を付けた文字列です。

.NOTES
 行番号は1から開始し、1づつ増加します。
 このバージョンでは行番号の開始する数や増加数を変更できません。

.LINK
 http://suyamasoft.blue.coocan.jp/PowerShell/Sample/Add-Number/index.html
#>
    [CmdletBinding()]
    [Outputtype([Object[]])]

    Param(
        [Parameter(Mandatory=$true, ValueFromPipeline=$true, HelpMessage="複数行の文字列")]
        [AllowEmptyString()]
        [String[]]$Lines,
        
        [Parameter(Mandatory=$false)]
        [String]$NumberFormat="00000: "
    )

    begin{
        $LineCount=0
    }

    process{
        foreach ($s in $Lines){
            $LineCount++
            Write-Output ($LineCount.ToString($NumberFormat) + $s)
        }    
    }
}
このページの上

下記はスクリプトをドットソースで読み込み、「Get-Help Add-Number -Full」コマンドを実行した結果です。

名前
    Add-Number
    
概要
    各行の左側に行番号を付けて表示します。
    
    
構文
    Add-Number [-Lines] <String[]> [[-NumberFormat] <String>] [<CommonParameters>]
    
    
説明
    各行の左側に指定した書式の行番号を付けて表示します。
    

パラメーター
    -Lines <String[]>
        複数の行の文字列です。
        
        必須                         true
        位置                         1
        既定値                       
        パイプライン入力を許可する   true (ByValue)
        ワイルドカード文字を許可する false
        
    -NumberFormat <String>
        行の番号の表示形式です。
        スペースが含まれる場合は、二重引用符(")で囲んでください。
        
        必須                         false
        位置                         2
        既定値                       00000:
        パイプライン入力を許可する   false
        ワイルドカード文字を許可する false
        
    <CommonParameters>
        このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
        Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
        OutBuffer, PipelineVariable、および OutVariable。詳細については、
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216) 
        を参照してください。
    
入力
    複数行のテキストです。
    
    
出力
    各行に行番号を付けた文字列です。
    
    
メモ
    
    
        行番号は1から開始し、1づつ増加します。
        このバージョンでは行番号の開始する数や増加数を変更できません。
    
    -------------------------- 例 1 --------------------------
    
    PS C:\>Get-ChildItem *.txt | Add-Number
    
    00001: C:\bin\PowerShell\Sample\a.txt
    00002: C:\bin\PowerShell\Sample\b.txt
    
    
    
    
    -------------------------- 例 2 --------------------------
    
    PS C:\>Add-Number -Lines ("a.txt", "b.txt") -NumberFormat "[00] "
    
    [01] a.txt
    [02] b.txt
    
    
    
    
    
関連するリンク
    http://suyamasoft.blue.coocan.jp/PowerShell/Sample/Add-Number/index.html



ヘルプの行頭のタブとスペースは削除され、自動で字下げされます。

このページの上