Zenn
😸

PowerShell Scriptの関数にJavadocのようなドキュメンテーションコメントをつけたい

に公開
PowerShell
tech

はじめに

VSCodeでPowerShellスクリプトを作成している際、PowerShellにはJavadocのようなコメント機能がないことに気付きました。コメント機能があれば便利だと感じ、試行錯誤の末、一つの形に落ち着いたので、その方法を共有したいと思います。

PowerShellにおけるドキュメンテーションコメント

PowerShellにも「コメントベースヘルプ」と呼ばれる仕組みがあり、関数やスクリプトに説明を付ける公式の方法が用意されています。

公式によると、関数のコメントは以下の3つのいずれかに書くと良いそうです。
1.関数本体の先頭。
2.関数本体の末尾。
3.functionの前。

個人的にfunctionの前に書くのが好きですが、docstring、Javadocと同じように関数本体の先頭またはfunctionの前に書くのがよいと思います。

コメントベースのヘルプキーワード

これだけは記載した方がよいという最低限のキーワードを抜粋しています。
詳細は公式を参照してください。

キーワード 説明
.SYNOPSIS 関数の簡単な説明
.DESCRIPTION 関数の詳細な説明
.PARAMETER 関数の引数の説明
.OUTPUTS 関数の戻り値の型と戻り値の説明

実例

function Get-Square {
<#
.SYNOPSIS
    与えられた数の平方を計算する関数です。

.DESCRIPTION
    この関数は、入力として受け取った数値の平方（自乗）を計算し、その結果を返します。
    引数として整数または浮動小数点数を受け入れ、計算した平方を返します。

.PARAMETER
    計算対象となる数値を指定します。この引数は整数または浮動小数点数として渡されるべきです。

.OUTPUTS
    [double] 計算結果として数値の平方を返します。戻り値は常に数値型（double）です。
#>
    param (
        [Parameter(Mandatory=$true)]
        [double]$Number
    )

    return $Number * $Number
}

実運用：vscodeにsnippetを登録する

実運用する上で毎回、手動で書くのは手間になるので、私はvscodeのsnippetに登録しています。

snippetに登録

  • vscodeの拡張機能にPowerShellをインストールする。

  • Ctrl + Shift + Pと押下して、snippetsと入力して、Configure Snippetsを選択。

  • 言語が出てくるので、PowerShellを選択するとpowershell.jsonを開くことができるので以下のコードを貼り付ける。

{
	"psHelpComment":{
		"prefix":"psHelpComment",
		"body":[
			"<#",
			".SYNOPSIS",
			"    Short description",
			".DESCRIPTION",
			"    Long description",
			"..PARAMETER
			"    Specifies the file name.",
			".OUTPUTS",
			"    Output from this cmdlet (if any)",
			"#>",
		]
	}
}
  • psHelpCommentと入力すると自動的にコメントが出てくる

Discussion