Configurable ParameterDescription Placement and Section Requirements in PSProvideCommentHelp

Summary of the new feature

As a user of PSScriptAnalyzer, I want to be able to configure where ParameterDescription comments appear and enforce required help sections (with optional order enforcement) in the PSProvideCommentHelp rule, so that I can align documentation with my project's standards and ensure consistency.

Proposed technical implementation details (optional)

1. Configurable ParameterDescription Placement

   • Add a new configuration option for PSProvideCommentHelp called ParameterDescriptionPlacement with two possible values:
     • WithCommentHelp (default): Parameter descriptions are included in the comment help block as today.
     • InParamBlock: Parameter descriptions are placed as inline comments in the param block itself.
   • The setting would control where parameter docs are generated and where the rule expects to find them.

2. Required Sections and Order Enforcement

   • Add a configuration option called RequiredSections, accepting an array of section names (e.g., ["Synopsis", "Description", "Parameters"]).
   • Add a boolean configuration option RequiredSectionsOrderMatters (default: false). If set to true, the order of the sections in the array is enforced in the help comment, and the rule will fail if the order is incorrect.
   • If RequiredSectionsOrderMatters is false, presence of all required sections is enforced, but order is not.

These options would give users more flexibility in how comment-based help is structured and validated.

What is the latest version of PSScriptAnalyzer at the point of writing

2024.6.0 (or latest at time of filing)

先定位 PSProvideCommentHelp 規則及其現有的設定處理。追蹤目前如何尋找參數描述和說明區段，然後在為 ParameterDescriptionPlacement、RequiredSections 和 RequiredSectionsOrderMatters 定義涵蓋範圍之前，找出該規則的測試。完成的標準是：兩種放置模式和必要區段的驗證（包括可選的順序）都能一致地強制執行。