ProvideCommentHelp

重大度レベル: 情報

デフォルト状態:有効

形容

このルールは、コメントベースのヘルプがない関数やコマンドレットを検出します。 すべてのPowerShellコマンドには、その目的、パラメータ、使用例を文書化するためのコメントベースのヘルプを含めるべきです。 PSScriptAnalyzerはコメントベースのヘルプの有無をチェックしますが、内容やフォーマットの検証は行いません。

コメントベースのヘルプについては、コマンド Get-Help about_comment_based_help を使うか、以下のリソースを参照してください。

例

非準拠

function Get-File
{
    [CmdletBinding()]
    Param
    (
        ...
    )

}

対応

<#
.Synopsis
    Short description
.DESCRIPTION
    Long description
.EXAMPLE
    Example of how to use this cmdlet
.EXAMPLE
    Another example of how to use this cmdlet
.INPUTS
    Inputs to this cmdlet (if any)
.OUTPUTS
    Output from this cmdlet (if any)
.NOTES
    General notes
.COMPONENT
    The component this cmdlet belongs to
.ROLE
    The role this cmdlet belongs to
.FUNCTIONALITY
    The functionality that best describes this cmdlet
#>

function Get-File
{
    [CmdletBinding()]
    Param
    (
        ...
    )

}

ルールの設定

Rules = @{
    PSProvideCommentHelp = @{
        Enable = $true
        ExportedOnly = $false
        BlockComment = $true
        VSCodeSnippetCorrection = $false
        Placement = 'before'
    }
}

パラメーター

Enable

このパラメータは、ScriptAnalyzerがこのルールに対してコードをチェックするかどうかを制御します。 ブール値も受け入れます。 既定値は $true です。

エクスポートのみ

このパラメータは、 Export-ModuleMember コマンドレットを使ってエクスポートされる関数やコマンドレットのみ違反が報告されるかどうかを制御します。 ブール値も受け入れます。 既定値は $true です。

ブロックコメント

このパラメータは、ルールによって返されるコメントヘルプのスタイルを制御します。 ブール値も受け入れます。 $trueに設定すると、コメントヘルプはブロックコメントスタイル(<#...#>)で返されます。 $falseに設定すると、コメントヘルプは各コメントラインが#で始まるラインコメントスタイルで返されます。 既定値は $true です。

VSCodeSnippetCorrection

このパラメータは、コメントヘルプがVisual Studio Codeのスニペット形式で返されるかどうかを制御します。 ブール値も受け入れます。 既定値は $false です。

位置付け

このパラメータは関数定義に関するコメントヘルプの位置を制御します。 文字列の値を受け入れます。 無効な値が指定された場合、プロパティの既定値は beforeになります。 既定値は before です。

指定できる値は次のとおりです。

  • before: コメントは関数定義の前に置かれます
  • begin: コメントは関数定義体の冒頭に置かれます
  • end: コメントは関数定義体の末尾に配置されます
  • 最終更新: