Explainer: Review and Update Analyzer Metadata

[rjmurillo]

Explainer: Review and Update Analyzer Metadata

Introduction/Overview

This document outlines the requirements for updating the diagnostic metadata for all Roslyn analyzers in the moq.analyzers project. The goal is to align with Roslyn best practices, improving the clarity and usefulness of analyzer diagnostics for developers. This work was previously started in PR #416 but was abandoned. This explainer is based on the work required to complete Issue #85.

Goals

• To improve the developer experience by providing clearer, more informative, and consistently categorized analyzer diagnostics.
• To ensure all analyzers follow established Roslyn best practices for diagnostic properties (Title, Description, MessageFormat, Category).
• To complete the work for all existing analyzers in the repository.

Non-Goals (Out of Scope)

• This effort will not involve creating any new analyzers.
• This effort may involve minimal changes to the core detection logic of an existing analyzer, but only what is necessary to supply data for the message format string.

User Stories

• As a developer using Moq with the analyzers, I want to see detailed, specific, and correctly categorized diagnostic messages so that I can quickly understand and fix issues in my code.

Functional Requirements

1. Update Description: All analyzers must have their Description property populated with a meaningful, localizable explanation of the rule's purpose. The current MessageFormat string, which is often a static sentence, should be moved to the Description.
2. Update MessageFormat: All analyzer MessageFormat properties must be updated to be a format string (e.g., "Sealed class '{0}' cannot be mocked") that includes placeholders ({0}, {1}, etc.) to provide context-specific details in the diagnostic message.
3. Update Analyzer Logic: The logic within each analyzer must be updated where necessary to capture and pass the relevant symbols or syntax nodes (e.g., the type name, the method name) to the Diagnostic.Create call for use in the MessageFormat string.
4. Update Category: All analyzers must be assigned to the Usage category instead of the current "Moq" category. This aligns with .NET's standard categories for code analysis rules.
5. Apply to All Analyzers: These changes must be systematically applied to every analyzer class located in the src/Analyzers/ directory.

Design Considerations (Optional)

• N/A

Technical Considerations (Optional)

• The implementation will require modifying the DiagnosticDescriptor for each analyzer.
• The Initialize method of each analyzer may need to be adjusted to extract the correct information to pass to the diagnostic.
• Refer to the abandoned PR (#416) for examples of how this was previously implemented.

Success Metrics

• A pull request is merged that successfully implements all the functional requirements.
• All analyzers in the project report diagnostics with detailed, formatted messages and are categorized under "Usage".
• Code review confirms that all analyzers have been updated.

Open Questions

• None.