Configurable ParameterDescription Placement and Section Requirements in PSProvideCommentHelp

Abierto
#2,133 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
csharp, powershell
Área
tooling

Línea de trabajo

Comienza localizando la regla PSProvideCommentHelp y su gestión de configuración existente. Rastrea cómo se encuentran actualmente las descripciones de parámetros y las secciones de ayuda, y luego identifica las pruebas de la regla antes de definir la cobertura para ParameterDescriptionPlacement, RequiredSections y RequiredSectionsOrderMatters. La tarea estará completada cuando se hagan cumplir de forma coherente ambos modos de colocación y la validación de las secciones requeridas, incluido el orden opcional.

Escrito por el modelo de indexación a partir del texto del issue.

Descripció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)

Lenguaje dominante
C#
Estrellas
2.2k
Forks
415
Merge medio
13 h 1 min
PR fusionados (30 d)
2

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de PowerShell/PSScriptAnalyzer

Todos los issues de PowerShell/PSScriptAnalyzer

Issues similares

Más issues de C#

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.