Improve analyzers docs #51209
Improve analyzers docs #51209
Conversation
There was a problem hiding this comment.
Pull request overview
This pull request improves the MSTest analyzers documentation by reorganizing the content for better browsability. The changes add category-based and concept-based organization to help developers find relevant analyzer rules more easily.
Changes:
- Restructured TOC to make category overview pages directly accessible (removed redundant "Overview" nesting)
- Enhanced category overview pages (design, performance, suppression, usage) with comprehensive tables and scenario-based guidance
- Added "Rules by concept" section to overview.md organizing rules by common testing scenarios
- Added "All rules (quick reference)" table in overview.md for easy lookup
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/navigate/devops-testing/toc.yml | Improved navigation structure by linking category pages directly and removing nested "Overview" items |
| docs/core/testing/mstest-analyzers/usage-rules.md | Added comprehensive rule table, organized rules by common scenarios (test structure, lifecycle, data-driven testing, assertions, TestContext, async, configuration) |
| docs/core/testing/mstest-analyzers/suppression-rules.md | Added detailed explanations of suppression rules with examples showing why each rule suppresses specific diagnostics |
| docs/core/testing/mstest-analyzers/performance-rules.md | Expanded with detailed guidance on test parallelization including when to enable/disable parallelization |
| docs/core/testing/mstest-analyzers/design-rules.md | Organized design rules by scenarios (structuring classes, initialization/cleanup patterns, assertions, test quality) |
| docs/core/testing/mstest-analyzers/overview.md | Added "Rules by concept" section and comprehensive "All rules" quick reference table |
Comments suppressed due to low confidence (5)
docs/core/testing/mstest-analyzers/performance-rules.md:40
- According to the Markdown Writing Style Instructions, write complete sentences in lists with proper punctuation. The bullet points should be complete sentences. For example, change "Tests have dependencies on shared resources" to "Tests have dependencies on shared resources." (add period) or rephrase as complete sentences.
- Tests have dependencies on shared resources
- Tests modify global state
- Tests require specific execution order
- You're debugging test failures
docs/core/testing/mstest-analyzers/usage-rules.md:66
- According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Validating test structure" to a noun-based title, such as "Test structure validation" or use an imperative like "Validate test structure".
### Validating test structure
docs/core/testing/mstest-analyzers/design-rules.md:33
- According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Structuring test classes" to a noun-based title, such as "Test class structure" or use an imperative like "Structure test classes".
### Structuring test classes
docs/core/testing/mstest-analyzers/design-rules.md:41
- According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Choosing initialization patterns" to a noun-based title, such as "Initialization patterns" or "Initialization pattern selection".
### Choosing initialization patterns
docs/core/testing/mstest-analyzers/design-rules.md:55
- According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Writing better assertions" to a noun-based title, such as "Better assertions" or "Assertion best practices".
### Writing better assertions
| - **[MSTEST0052](mstest0052.md)**: Use AutoDetect for DynamicDataSourceType | ||
| - **[MSTEST0062](mstest0062.md)**: Avoid out/ref parameters | ||
|
|
||
| ### Writing better assertions |
There was a problem hiding this comment.
According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Writing better assertions" to a noun-based title, such as "Better assertions" or "Assertion best practices".
This issue also appears in the following locations of the same file:
- line 66
|
|
||
| | Rule ID | Title | Severity | Fix Available | | ||
| |---------|-------|----------|---------------| | ||
| | [MSTEST0004](mstest0004.md) | Public types should be test classes | Info | Yes | |
There was a problem hiding this comment.
Is it necessary to document the default severity and whether a fix is available here? It adds additional maintenance cost for docs when the information is present in the analyzer page.
There was a problem hiding this comment.
Not required, my idea was to simplify lookup so you don't need to browse down jsut to have a glance at what's available by default. As for the maintenance cost, I agree there is a risk, I was assuming it would be mitigated with Copilot reviews.
Summary
Make it easier to browse all rules, rules by category and also allows people browsing the docs to understand the rules that could be interesting by concepts (avoiding the hassle to browse all rules).
Internal previews