PowerShell / PowerShell/PSScriptAnalyzer

Parameter Help auto generation in PowerShell Functions

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

还没有人认领这个 Issue。

Issue-Enhancement Up for Grabs
主要语言
C#
星标
2.2k
派生
414
平均合并
13 小时 1 分钟
30 天内合并 PR
2

描述

Prerequisites
  • I have written a descriptive issue title.
  • I have searched all issues to ensure it has not already been reported.
Summary

If you go above the parameter block of a function and write "##" the parameter help template is pre-generated automatically by the PowerShell Extension. However currently this generates:

<#
    .SYNOPSIS
    Short description
    
    .DESCRIPTION
    Long description
    
    .PARAMETER exampleParam
    Parameter description
    
    .EXAMPLE
    An example
    
    .NOTES
    General notes
    #>

However, it is best practice to also specify the return value of your function by using ".OUTPUTS", therefore it would be nice if this could be added to the default template / if the default template could be configured in the settings.json.

Proposed Design

This could be accomplished by either:

Static Design

Add ".OUTPUTS" to the current template

Dynamic Design

Add the possibility to specify the fields in the template in a list like:

 "powershell.extentention" : {
      "parameterHelp" : {
           "generatorTemplateFields" : [
               ".SYNOPSIS", ".DESCRIPTION", ".PARAMETER", ".EXAMPLE", ".NOTES", ".OUTPUTS"
            ]
      }
 }

贡献指南

打开贡献指南

从这里开始

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

调研方向

未指定文件或测试。首先定位参数帮助生成器和 PowerShell 扩展的设置定义,然后将现有模板与提议的 .OUTPUTS 字段和 generatorTemplateFields 设置进行比较。完成标准是:要么将 .OUTPUTS 添加到生成的帮助中,要么记录并实现可配置的模板字段,并为所选行为提供覆盖。

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

评估

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

把新 issue 发到你的邮箱

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