PowerShellのヘルプメッセージ

自前のプログラムを作成・公開する場合には、
使い方の情報を「ヘルプメッセージ」として開示することが多いです。

↑この手の文は一般的に「ヘルプメッセージ」と呼ぶものと思ってましたが、
どうやらPowerShellではヘルプトピックというらしい。
検索で作り方が出なかったのは、キーワード「ヘルプメッセージ」が悪かったようで。。。

また、PowerShellでは、上記ヘルプメッセージも
MamlCommandHelpInfoオブジェクトとして定義されています。
その恩恵でクラスからほしい情報のみを取り出すことも容易であり、
独自ヘルプトピックの使用にも活用できます。

以下、スクリプトのコメントベースのヘルプで記述できる項目です。
キーワード名が「－」になっている項目は、自動で生成されるコンテンツです。

キーワード名	ざっくりとした説明	指定 可能 回数	ヘルプトピック での表題	MamlCommandHelpInfo クラスのプロパティ名
－	関数／スクリプト名。	－	名前	Name
.SYNOPSIS	関数／スクリプトの簡単な説明。	1	概要	Synopsis
－	関数／スクリプトのI/F。	－	構文	syntax
.DESCRIPTION	関数／スクリプトの詳細な説明。	1	説明	description
.PARAMETER パラメータ名	パラメータの説明。	N	パラメーター	parameters
－	パラメータの属性一覧。パラメータのところに出力される。	－	－	－
.INPUTS	関数／スクリプトにパイプ可能なオブジェクト型の説明。	1	入力	inputTypes
.OUTPUTS	関数／スクリプトから返されるオブジェクト型の説明。	1	出力	returnValues
.NOTES	関数／スクリプトに関する追加情報。	1	メモ	－
.EXAMPLE	関数／スクリプトの使用例。各例に本キーワードを指定。	N	1	examples
.LINK	関連トピックの情報。	N	関連するリンク	relatedLinks
－	注釈情報（get-helpコマンドの使い方）。	－	注釈	－

コマンドベースのヘルプを記述できるのは以下の3箇所のいずれかになります。
①関数本体の先頭
②関数本体の末尾
③Functionキーワードの直前（複数行の空白行をおいてはならない）

作成例（ヘルプを①に記述した場合）：

# sample4.ps1
Function Show-SampleTopic
{
<# .SYNOPSIS SYNOPSISには概要を書く。 .DESCRIPTION DESCRIPTIONには詳細説明を書く。 改行してみた。 .PARAMETER Param1 1つ目のパラメータ。 .PARAMETER Param2 2つ目のパラメータ。 改行してみた。規定値は"txt"。 .INPUTS なし。オブジェクトを Show-TopicSample にパイプすることはできません。 .OUTPUTS System.String。Show-TopicSample は、何か文字列を返します。 .EXAMPLE C:\PS> st -Param1 "File"
File

.EXAMPLE
C:\PS> st -Param1 "File" -Param2 "doc"

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

説明文その3
------------
長いので改行してみた。

説明が複数行に
わたっても
問題ありません。

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

.LINK
Set-SampleTopic

.NOTES
追加情報いろいろ。
改行してみた。
#>
Param
([string]$Param1,[string]$Param2 = "txt")
Process
{ $Param1 + $Param2 | Out-Host}
}
Get-Help Show-SampleTopic -Full

↓↓↓↓上記スクリプトの出力（若干歪んでいます）↓↓↓↓

名前
Show-SampleTopic

概要
SYNOPSISには概要を書く。

構文
Show-SampleTopic [[-Param1] ] [[-Param2] ] []


説明
DESCRIPTIONには詳細説明を書く。
改行してみた。


パラメーター
-Param1
1つ目のパラメータ。

必須 false
位置 1
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する

-Param2
2つ目のパラメータ。
改行してみた。規定値は"txt"。

必須 false
位置 2
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する


このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
OutBuffer、および OutVariable。詳細については、
「get-help about_commonparameters」と入力してヘルプを参照してください。

入力
なし。オブジェクトを Show-TopicSample にパイプすることはできません。


出力
System.String。Show-TopicSample は、何か文字列を返します。


メモ
追加情報いろいろ。
改行してみた。

-------------------------- 例 1 --------------------------

C:\PS>st -Param1 "File"

File


-------------------------- 例 2 --------------------------
C:\PS>st -Param1 "File" -Param2 "doc"


-------------------------- 例 3 --------------------------
C:\PS>st "File" "doc"

説明文その3
------------
長いので改行してみた。

説明が複数行に
わたっても
問題ありません。


関連するリンク
オンライン バージョン: http://www.sample.com/st.html
Show-SampleTopic

参考コマンド：

Get-Help about_Comment_Based_Help

修正履歴：
2010/1/23 サンプルコードの表示のゆがみを修正
2010/1/30 MamlCommandHelpInfoオブジェクトに関する情報を追記