Configurable ParameterDescription Placement and Section Requirements in PSProvideCommentHelp

Bắt đầu bằng cách xác định rule PSProvideCommentHelp và phần xử lý cấu hình hiện có của rule. Theo dõi cách các mô tả tham số và các phần trợ giúp hiện được tìm thấy, sau đó xác định các kiểm thử của rule trước khi định nghĩa phạm vi bao phủ cho ParameterDescriptionPlacement, RequiredSections và RequiredSectionsOrderMatters. Công việc được hoàn tất khi cả hai chế độ đặt vị trí và việc xác thực các phần bắt buộc, bao gồm cả thứ tự tùy chọn, đều được thực thi nhất quán.

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)