Configurable ParameterDescription Placement and Section Requirements in PSProvideCommentHelp

未关闭
#2,133 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
停滞
技术栈
csharp, powershell
领域
tooling

调研方向

首先定位 PSProvideCommentHelp 规则及其现有的配置处理。跟踪当前如何查找参数描述和帮助部分,然后在为 ParameterDescriptionPlacement、RequiredSections 和 RequiredSectionsOrderMatters 定义覆盖范围之前,确定该规则的测试。完成的标准是:两种放置模式和必需部分的验证(包括可选的顺序)都得到一致执行。

由索引模型根据 Issue 内容生成。

描述

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)

主要语言
C#
星标
2.2k
派生
422
平均合并
2 小时 23 分钟
30 天内合并 PR
25

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

PowerShell/PSScriptAnalyzer 的其他 Issue

查看 PowerShell/PSScriptAnalyzer 的全部 Issue

相似的 Issue

更多 C# Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。