Description
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.