PowerShell / PowerShell/PSScriptAnalyzer
Warn on syntax that will cause comment-based help to fail to be discovered/usable
@kapilmb ci sta già lavorando.
Dal 23/4/2016.
- Lingua principale
- C#
- Stelle
- 2.2k
- Fork
- 414
- Merge medio
- 13h 1m
- PR unite (30g)
- 2
Descrizione
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.
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Valutazione
Questa issue non è ancora stata valutata.