#comment based help

動機

Githubに公開されているものを見ていると、コメントブロックに関数の説明を特定の書式で書いていることに気づきます。どうやら、コメントベースのヘルプということのようです。そこで、少し調べてみました。

コメントベース

コメントブロック<# 〜 #>の中に特定の記述をすることで、Get-Helpコマンドレットするとヘルプが表示できるという優れものであります。以下のようにすれば、ファイル中に関数などの実態がなくてもパースされてヘルプが表示されました。

<# .SYNOPSIS コメントベースのヘルプの例です。 .DESCRIPTION コメントベースのヘルプの例です。 こういうのがあると、引継ぎがしやすいかもしれません。 .EXAMPLE C:\> Get-CommentSample -Sample "this is comment." .INPUTS 入力される.Netの型などを記載しておくとよいようです。 .OUTPUTS 出力される.Netの型などを記載しておくとよいようです。 .LINK https://technet.microsoft.com/ja-jp/library/hh847834.aspx .NOTES ここには注釈をいれておくと、気を付けるべき内容を伝えることができます。 #>

実際にやってみると、以下のようになります。

しかし、やってみて気づいたのですがMSDNには書いてあるパラメータの説明を書くことのできる「.PARAMETER」が動作していないような気がします。 書き方が悪いのか？

about_Comment_Based_Help

補足

調べてみると、こういったコメントブロックを追加してくれるIDEがあるようですね。

PowerShell Studio

こちらは有償っぽいので試していません。オープンソースでもありそうな予感がしなくはないのですが。

まとめ

自作したスクリプトや関数を引き継ぐときに、メンバーが「Get-Help」すればいいという習慣があれば自作するときにコメントにこれらを書いておく文化が根付くように思ったりしますが…甘すぎますかね。 しかしドキュメントまでいかなくても、「これって何がどうなるの？」ということの概要までわかれば多少は安心感が出るのでよさそうに思います。 もちろん、これで得られる説明にあった挙動をする必要がありますが。