New function: Show-RuleHelp

[juneb]

I have a function to submit, Show-RuleHelp, which opens the .md file of help for each rule. Before I do a PR, I want to know if you're interested in including it and, if so, how?

-- Add the script containing the function to ScriptsToProcess
-- Add the function to PSScriptAnalyzer.psm1 + FunctionsToExport in the psd1

You can see the code at https://github.com/juneb/Development/blob/master/Show-RuleHelp.ps1.

[kapilmb]

@juneb This looks like a very useful addition. I would like to propose a slightly different approach though - perhaps we can add a switch to Get-ScriptAnalyzerRule to show help instead of adding a new cmdlet? What do you think?

[juneb]

No, I wouldn't do it that way. The philosophy of PowerShell is small, single-feature commands. That's why we created Get-Command separate from Get-Help.

Instead, I made the Name parameter take value from pipeline, so you can pipe Get-ScriptAnalyzerRule to Get-RuleHelp. I also made sure that the parameter names/types were the same.

But, it's your module, so I'm fine with whatever you decide.

[kapilmb]

I agree with the philosophy but I don't think Get-ScriptAnalyzerRule and Get-RuleHelp are completely analogous to Get-Command and Get-Help - the scope of Get-Help is much wider than that of just showing help for commands, whereas, Get-RuleHelp would provide help only for a rule.

Would like to loop in @joeyaiello here to add more perspective, because I think adding a new cmdlet to the module warrants more discussion.

[joeyaiello]

First, looks super cool, I could definitely see this being useful to people.

On to the design. I understand both points of view. Here's my thinking:

• if it were to go on Get-ScriptAnalyzerRule it should probably just be a property on each rule object. However, that probably requires that the help content be readily available on disk, and regardless of whether the property was output, it'd get attached to each object.
• Seeing as this function is hitting the web
• The crux of this discussion should probably be around whether it's a good idea for a cmdlet to go hit the web directly. There's a few problems with that approach:. First, it's slow, goes out to the web every time, etc. Also, you'd want to hit the rule documentation for the version of PSSA installed on the box (and definitely not the latest code in development as the rule could very well have changed between versions. (And in this code, it's actually feasible that someone could ask for rule documentation for a rule that's not even installed on their machine, and get the help.)

What are everyone's thoughts on packing rule documentation with each module release?

[kapilmb]

@joeyaiello shipping rule documentation sounds like a great idea as it would prevent the issues (hitting the web and potential doc version mismatch) that you've mentioned. And if we ship the rule documentation then it is relatively straightforward to include the documentation as a property of RuleInfo object. An added advantage of this approach is that PowerShell/vscode-powershell extension can use the property to show rule documentation (#736), if a user wants to see it.

[daviwil]

Yep, I like that approach as well. A baked-in snapshot of the documentation will be a lot more useful to the user.

[juneb]

Agreed. This also solves the problem of finding online docs for custom rules.

[juneb]

The downside is that we need to design, implement, and test a rule documentation format, which can take a while. (I suggest that we start with something very simple like a .md template like the ones already in use.) Then, we need to find a way to install and update the rule doc files. Deja vu...