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)

Commencez par localiser la règle PSProvideCommentHelp et sa gestion de configuration existante. Suivez la manière dont les descriptions de paramètres et les sections d’aide sont actuellement trouvées, puis identifiez les tests de la règle avant de définir la couverture pour ParameterDescriptionPlacement, RequiredSections et RequiredSectionsOrderMatters. Le travail est terminé lorsque les deux modes de placement et la validation des sections requises, y compris l’ordre facultatif, sont appliqués de manière cohérente.