DocQuality.Analyzers 0.1.4

DocQuality.Analyzers

⚠️ Early stage: This project is not fully tested. Bug reports, feedback, and contributions of any kind are very welcome — see Contributing.

Roslyn analyzers that enforce XML documentation comment quality on public C# members. Catch empty tags, missing parameters, undocumented return values, and more — at compile time.

Motivation

C# already ships two compiler warnings that encourage XML documentation:

These warnings are useful, but they only check whether a comment exists — not whether it actually says anything meaningful. In practice, many tools (IDE snippets, AI assistants, "generate XML doc" refactorings) auto-generate documentation stubs like:

/// <summary></summary>
/// <param name="value"></param>
/// <returns></returns>
public int Process(int value) { … }

This satisfies CS1591 and CS1573 — no compiler warnings — yet the documentation is completely empty. Consumers see blank tooltips and generated API docs with no descriptions.

DocQuality.Analyzers bridges that gap. It works alongside CS1591 and CS1573 by verifying that the documentation content is actually filled in: summaries are not empty, every <param> tag contains a description, <returns> is present and non-blank, and so on. Together, the built-in warnings ensure documentation exists, and DocQuality ensures it is meaningful.

Diagnostics

Which diagnostics apply where?

¹ Only when the type has a primary constructor (C# 12+).

All diagnostics target public members only and are enabled by default. Members marked with override or <inheritdoc /> are skipped.

Installation

dotnet add package DocQuality.Analyzers

Or via the NuGet Package Manager in Visual Studio.

Usage

Once installed, the analyzer runs automatically as part of your build. Violations appear as warnings (or suggestions) in your IDE and build output.

Example — DOC001 (empty summary on a class):

/// <summary></summary>  // ⚠️ DOC001: Summary tag is empty
public class MyService { }

Example — DOC001 (empty summary on a method):

/// <summary></summary>  // ⚠️ DOC001: Summary tag is empty
public void DoSomething() { }

Example — DOC003 (missing param on a record):

/// <summary>Represents a person.</summary>
// ⚠️ DOC003: Parameter 'Name' has no corresponding <param> tag
// ⚠️ DOC003: Parameter 'Age' has no corresponding <param> tag
public record Person(string Name, int Age);

Example — DOC004 (missing returns on a method):

/// <summary>Gets the current count.</summary>
// ⚠️ DOC004: Returns a value but has no <returns> tag
public int GetCount() => _count;

Suppressing a diagnostic

You can suppress individual diagnostics with #pragma or [SuppressMessage]:

#pragma warning disable DOC001
/// <summary></summary>
public void DoSomething() { }
#pragma warning restore DOC001

Configuration

Severity

Severity levels can be adjusted in your .editorconfig:

[*.cs]
dotnet_diagnostic.DOC001.severity = error
dotnet_diagnostic.DOC003.severity = none

Behavior options

The following .editorconfig options control which checks are active:

Generated code exclusion

By default, all diagnostics run on generated files too. You can exclude generated code (files ending in .g.cs, .designer.cs, .generated.cs, or containing [GeneratedCode]) per-diagnostic:

* These defaults are set in the .editorconfig shipped with the package. The analyzer's built-in default is false; the packaged .editorconfig overrides DOC001 and DOC002 to true.

Example .editorconfig

[*.cs]
# Promote empty-summary to an error
dotnet_diagnostic.DOC001.severity = error

# Disable the missing-param-tag check
dotnet_diagnostic.DOC003.severity = none

# Don't require <returns> tags
dotnet_diagnostic.DOC004.require_returns = false

# Exclude generated code from DOC005
dotnet_diagnostic.DOC005.exclude_generated_code = true

Code fixes

The analyzer ships with code fixes for all five diagnostics:

All code fixes insert TODO: document this as placeholder text.

Contributing

Contributions are very welcome! The project is in early development and there's plenty of room to help:

• 🐛 Bug reports — open an issue if something doesn't behave as expected
• ✅ Tests — test coverage is limited; adding tests for edge cases is a great place to start
• 💡 New diagnostics — have an idea for another doc quality rule? Open an issue to discuss it
• 📝 Documentation — improvements to this README or inline docs are always appreciated

To get started:

git clone https://github.com/rubenseggers/DocQuality.Analyzers.git
cd DocQuality.Analyzers
dotnet build
dotnet test

Please open an issue before starting significant work, so we can discuss the approach.

License

MIT