Configurable ParameterDescription Placement and Section Requirements in PSProvideCommentHelp

[MariusStorhaug]

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)