PowerShell / PowerShell/PSScriptAnalyzer

Warn on syntax that will cause comment-based help to fail to be discovered/usable

Aberta
#500 8 comentários 1 reação 1 responsável Ver no GitHub

@kapilmb já está trabalhando nisso.

Desde 23/4/2016.

Issue - Discussion Issue - New Rule Up-for-Grabs
Linguagem predominante
C#
Estrelas
2.2k
Forks
414
Merge médio
13h 1min
PRs com merge (30d)
2

Descrição

Related to this item on UserVoice:
https://windowsserver.uservoice.com/forums/295047-general-feedback/suggestions/13383489-show-syntax-errors-in-powershell-comment-based-hel

Today comment-based help is very fragile, and there are multiple ways you can do something with it that will cause the help to fail to load in PowerShell. PowerShell would do well to report a warning when such a failure is discovered, but that change would only happen in PSvLatest, while a PSScriptAnalyzer rule would resolve this for PSv3+, so I'd like to see this improved with a new rule in PSScriptAnalyzer.

Here are the issues I have noticed people mention so far:

Invalid (mispelled, incorrect) comment-based help keywords.
e.g. The incorrect
.DESCIPRITION
vs the correct
.DESCRIPTION
Note for this issue, that includes starting a line with a period, such as ".NET Framework". The parsing logic should split on lines that start with period and warn if any line keywords don't match up with what is in the comment-based help keyword list.

Incorrect placement of comment-based help keyword values.
e.g. The incorrect
.PARAMETER
<parameter_name>
vs. the correct
.PARAMETER <parameter_name>
The parsing logic should verify the syntax for each keyword.

Spaces between comment-based help and a function, when placing it outside of a function.
e.g. The incorrect
<#
.SYNOPSIS
whatever

>

function Test-CommentBasedHelp {}
vs the correct
<#
.SYNOPSIS
whatever

>

function Test-CommentBasedHelp {}
(NOTE: I'm reporting this one because I saw others mention it but I could not reproduce it using 5.0.10586.122, so maybe this applies only to earlier versions of PowerShell? Some testing is required to nail this one down -- see the discussion point below)

These are only a few examples. I think it would be good to mark this as Discussion and then let others share specific issues they have run into with comment-based help, and then address them with a rule in PSScriptAnalyzer that watches script authors' backs in this area.

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.