|
| 1 | +## Example Analysis |
| 2 | + |
| 3 | +### What is the purpose of example analysis? |
| 4 | +As we know, our cmdlet help markdown is handwritten, which is an error-prone process. Example analysis is one of steps of static analysis, which checks the syntax correctness and completeness of cmdlet help markdown, especially for code blocks in example sections. |
| 5 | + |
| 6 | +### What will be checked by example analyzer? |
| 7 | +Example analyzer will check |
| 8 | +- if there are any missing section heading, like '## EXAMPLES', '## PARAMETERS' and so on. |
| 9 | +- if code block type is defined clearly like ```powershell |
| 10 | +- if code block is separated into two parts: ```powershell and ```output |
| 11 | +- if customized rules are violated. Customized rules include |
| 12 | + - Invalid_Cmdlet |
| 13 | + - Is_Alias |
| 14 | + - Capitalization_Conventions_Violated |
| 15 | + - Unknown_Parameter_Set |
| 16 | + - Invalid_Parameter_Name |
| 17 | + - Duplicate_Parameter_Name |
| 18 | + - Unassigned_Parameter |
| 19 | + - Unassigned_Variable |
| 20 | + - Unbinded_Expression |
| 21 | + - Mismatched_Parameter_Value_Type |
| 22 | + |
| 23 | +### What will be ignore by example analyzer? |
| 24 | + - If the example begins with `<!-- Aladdin Generated Example -->` or matches with regex `<!-- Skip.*-->`, its scan will be skipped. |
| 25 | + |
| 26 | +### How to run example analyzer locally to debug issues reported in CIs |
| 27 | +Run following script in PowerShell console, which requires PSScriptAnalyzer installed on local |
| 28 | +```powershell |
| 29 | +tools/StaticAnalysis/ExampleAnalyzer/Measure-MarkdownOrScript.ps1 -MarkdownPaths {your-help-folder} -RulePaths tools/StaticAnalysis/ExampleAnalyzer/AnalyzeRules/*.psm1 |
| 30 | +``` |
| 31 | + |
| 32 | +### TroubleShooting |
| 33 | + - If a cmdlet is recognized as Invalid_Cmdlet, most likely its module is not imported correctly. Check its import process and configuration. If it's correct, it may be caused by parallel importing all psd1 files. Currently, the workaround is suppressing false positive. Maybe only importing changed modules are one of potential solutions. |
| 34 | + |
| 35 | +### Miscellaneous |
| 36 | + - Storage module has not been separated into ```powershell and ```output as their examples contain many outputs. They skips scan by regex `<!-- Skip.*-->` at the beginning of code block. |
0 commit comments