ja-JP/about_Comment_Based_Help.help.txt
|
TOPIC about_Comment_Based_Help 簡単な説明 関数やスクリプトに、コメントを使ってヘルプを記述する方法を説明します。 記述したヘルプは Get-Help で表示できます。 詳細な説明 コメントベースのヘルプは、コメント内に「ドット (.) で始まる特殊な キーワード」を書くことで作成します。Get-Help は、このコメントを XML ベースのヘルプと同じように整形して表示します。 コメントは次の 2 つの書式のどちらでも書けます。 - 行コメント: 各行の先頭に # を付ける - ブロックコメント: <# と #> で囲む（こちらが一般的） ブロックコメントの例: <# .SYNOPSIS ファイルを安全にコピーします。 .DESCRIPTION Copy-Safe 関数は、コピー先に同名ファイルが無い場合のみ コピーを実行します。 #> ヘルプの配置場所 関数の場合、コメントベースのヘルプは次のいずれかに置けます。 - 関数本体の先頭（{ の直後） - 関数本体の末尾（} の直前） - 関数定義の直前（間の空行は 1 行まで） スクリプトの場合は、次のいずれかに置きます。 - ファイルの先頭（署名付きスクリプトではこの位置が推奨） - ファイルの末尾 先頭に置く場合、最初の関数定義との間は 2 行以上空けてください。 主なキーワード .SYNOPSIS コマンドの簡単な説明（1 回だけ）。 .DESCRIPTION 詳細な説明（1 回だけ）。 .PARAMETER <名前> パラメーターの説明。パラメーターごとに繰り返し書けます。 .EXAMPLE 使用例。複数書けます。コマンドと、必要なら出力を続けます。 .INPUTS パイプライン経由で渡せる入力オブジェクトの型。 .OUTPUTS コマンドが返すオブジェクトの型。 .NOTES 補足情報。 .LINK 関連トピックやコマンド名。URL も書けます。 .COMPONENT / .ROLE / .FUNCTIONALITY Get-Help -Category などでの絞り込み用メタデータ。 .FORWARDHELPTARGETNAME / .FORWARDHELPCATEGORY 別のコマンドのヘルプへ転送（リダイレクト）します。 .EXTERNALHELP XML ベースの外部ヘルプファイルを参照します。 .REMOTEHELPRUNSPACE ヘルプを格納したセッションを指定します。 自動生成される項目 Get-Help は、Name・Syntax・パラメーター一覧・共通パラメーターの節・ Remarks を自動的に生成します。これらはコメントで直接制御できません。 完全な例（関数） function Get-Function { <# .SYNOPSIS サンプル関数です。 .DESCRIPTION Get-Function は、引数に応じてメッセージを返すサンプルです。 .PARAMETER Name 表示する名前を指定します。 .EXAMPLE Get-Function -Name "鈴木" こんにちは、鈴木 さん と表示します。 .INPUTS なし。 .OUTPUTS System.String .NOTES これはコメントベースヘルプのサンプルです。 .LINK about_Comment_Based_Help #> param ([string]$Name) "こんにちは、$Name さん" } # 表示するには Get-Help Get-Function -Full 関連項目 about_Functions about_Functions_Advanced about_Scripts Get-Help ---- 原文: PowerShell-Docs (CC BY 4.0) の翻訳 / PSHelpJaJP |