Skip to content

Commit 2cb03f7

Browse files
authored
Add engineer docs for example analyzer (#26663)
* Create example-analyzer.md * refine docs * debug way
1 parent 5a3a0e2 commit 2cb03f7

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
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

Comments
 (0)