Configurable ParameterDescription Placement and Section Requirements in PSProvideCommentHelp

Aperta
#2,133 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
csharp, powershell
Ambito
tooling

Direzione di ricerca

Inizia individuando la regola PSProvideCommentHelp e la relativa gestione della configurazione esistente. Traccia il modo in cui vengono attualmente individuate le descrizioni dei parametri e le sezioni della guida, quindi identifica i test della regola prima di definire la copertura per ParameterDescriptionPlacement, RequiredSections e RequiredSectionsOrderMatters. Il lavoro è completato quando entrambe le modalità di posizionamento e la convalida delle sezioni obbligatorie, incluso l'ordinamento facoltativo, vengono applicati in modo coerente.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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)

Lingua principale
C#
Stelle
2.2k
Fork
422
Merge medio
2h 23m
PR unite (30g)
25

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di PowerShell/PSScriptAnalyzer

Tutte le issue di PowerShell/PSScriptAnalyzer

Issue simili

Altre issue su C#

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.