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)

Beginne damit, die PSProvideCommentHelp-Regel und ihre bestehende Konfigurationsbehandlung zu finden. Verfolge, wie Parameterbeschreibungen und Hilfeabschnitte derzeit gefunden werden, und identifiziere dann die Tests der Regel, bevor du die Abdeckung für ParameterDescriptionPlacement, RequiredSections und RequiredSectionsOrderMatters definierst. Die Arbeit ist abgeschlossen, wenn beide Platzierungsmodi und die Validierung erforderlicher Abschnitte, einschließlich der optionalen Reihenfolge, konsistent durchgesetzt werden.