Skip to main content
This guide covers common problems you might encounter when using CommentSense and how to resolve them.

​
Installation and Setup Issues

Symptoms: No CSENSE diagnostics show up in the Error List or in the IDE.Possible Causes:
  1. CommentSense is not installed
  2. XML documentation generation is disabled
  3. The analyzer is disabled in project settings
  4. IDE analyzer support is turned off
Solutions:
1

Verify Installation

Check that the CommentSense NuGet package is installed:
dotnet list package | grep CommentSense
If not installed, add it:
dotnet add package CommentSense.Analyzers
2

Enable XML Documentation

CommentSense requires XML documentation generation. Add to your .csproj:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
Without this, CSENSE000 will appear warning you that documentation parsing is disabled.
3

Check Analyzer Settings

Ensure analyzers are not disabled:
<PropertyGroup>
  <!-- Should NOT be set to false -->
  <RunAnalyzersDuringBuild>true</RunAnalyzersDuringBuild>
  <RunAnalyzersDuringLiveAnalysis>true</RunAnalyzersDuringLiveAnalysis>
</PropertyGroup>
4

Restart IDE

Sometimes the IDE needs a restart to load new analyzers:
  • Visual Studio: Close and reopen the solution
  • VS Code: Reload window (Ctrl+Shift+P → “Reload Window”)
Symptom: You see this warning at the project level.Cause: Your project doesn’t have <GenerateDocumentationFile>true</GenerateDocumentationFile> in the .csproj.Solution:Add the required property to your project file:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
Or enable it for all projects in a Directory.Build.props file:
<Project>
  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
</Project>
Symptom: Both CommentSense diagnostics (CSENSE001) and compiler warnings (CS1591) appear.Cause: The suppressor is not running, or you have manual <NoWarn> entries.Solution:
  1. Remove manual suppressions from .csproj: 
    <!-- REMOVE THIS -->
<PropertyGroup>
  <NoWarn>CS1591</NoWarn>
</PropertyGroup>
  2. Verify the suppressor is loaded: The CommentSenseSuppressor should automatically suppress CS1591, CS1573, etc. Check that:
    • CommentSense is properly installed
    • Your SDK version supports DiagnosticSuppressor (requires .NET 5+ SDK or Visual Studio 2019 16.9+)
  3. Check conditional suppression settings: If you have comment_sense.enable_conditional_suppression = true, some warnings may intentionally show for excluded members.

​
Configuration Issues

Symptoms: Configuration changes in .editorconfig don’t affect CommentSense behavior.Solutions:
1

Check File Location

Ensure .editorconfig is in the project root or a parent directory.
2

Verify Syntax

Check for typos in option names:
[*.cs]
# Correct
comment_sense.visibility_level = protected

# Incorrect (typo)
commentsense.visibility_level = protected
3

Check Section Matching

Ensure the section header matches your files:
# Matches all .cs files
[*.cs]
comment_sense.visibility_level = public

# Matches only files in src/Api directory
[src/Api/**/*.cs]
comment_sense.visibility_level = public
4

Rebuild Solution

After changing .editorconfig, rebuild:
dotnet clean
dotnet build
5

Restart IDE

Some IDEs cache configuration. Restart to reload.
Use .editorconfig or .globalconfig to set severity:
[*.cs]
# Disable CSENSE016 (low quality documentation)
dotnet_diagnostic.CSENSE016.severity = none

# Make CSENSE014 (missing value tag) a suggestion instead of warning
dotnet_diagnostic.CSENSE014.severity = suggestion

# Promote CSENSE001 (missing documentation) to error
dotnet_diagnostic.CSENSE001.severity = error
Available severities: none, silent, suggestion, warning, error
Possible Causes:
  1. .editorconfig not committed to source control
  2. CI environment uses different SDK version
  3. Build script overrides settings
Solutions:
  • Commit .editorconfig to git: 
    git add .editorconfig
git commit -m "Add CommentSense configuration"
  • Verify SDK version in CI matches local: 
    dotnet --version
  • Check for <NoWarn> or <TreatWarningsAsErrors> in CI-specific props files

​
Code Fix Issues

Symptoms: The lightbulb doesn’t show up, or it shows but has no CommentSense fixes.Solutions:
  1. Check diagnostic severity: Code fixes only appear for diagnostics with warning or error severity (not suggestion or none).
  2. Verify cursor position: Place the cursor directly on the diagnostic (usually the member name).
  3. Use the keyboard shortcut: Press Ctrl + . (or Alt + Enter in some IDEs) to explicitly invoke the code fix menu.
  4. Restart the IDE: Sometimes the code fix provider needs a reload.
Symptoms: Fix All applies some fixes but not others, or produces unexpected results.Causes & Solutions:
  1. Multiple diagnostics on the same member: CommentSense groups diagnostics by member and applies them together. If fixes conflict, some may not apply. Solution: Apply fixes one at a time, or review the Fix All preview.
  2. Fix All scope: Ensure you’re using the right scope:
    • Fix All in Document: Current file only
    • Fix All in Project: All files in current project
    • Fix All in Solution: All projects
    Select the scope in the Fix All dialog.
  3. Files with syntax errors: Fix All skips files with compilation errors. Solution: Fix syntax errors first, then run Fix All.
Symptoms: After applying a code fix, the documentation has syntax errors or is incorrectly formatted.This should be rare. If it happens:
  1. Report a bug: Include the original code and the fix result
  2. Workaround: Undo the fix (Ctrl+Z) and apply manually
  3. Check for mixed comment styles: Ensure you’re using either /// (single-line) or /** */ (multi-line), not both

​
Performance Issues

Symptoms: Visual Studio or other IDE becomes sluggish when editing code.Solutions:
  1. Disable live analysis for large files: In Visual Studio: Tools → Options → Text Editor → C# → Advanced → Enable full solution analysis → Uncheck
  2. Reduce visibility level: Analyze fewer members: 
    [*.cs]
# Only analyze public members (fewer diagnostics)
comment_sense.visibility_level = public
  3. Exclude member types: 
    [*.cs]
comment_sense.exclude_constants = true
comment_sense.exclude_enums = true
  4. Disable expensive rules: 
    [*.cs]
# Disable similarity analysis (can be slow on large files)
comment_sense.similarity_threshold = 0.0

# Disable deep exception scanning
comment_sense.scan_called_methods_for_exceptions = false
Symptoms: Build times increase significantly with CommentSense.Solutions:
  1. Use incremental builds: 
    dotnet build --no-incremental false
  2. Run analyzers only on changed files (advanced): Use build caching and only analyze modified files.
  3. Disable analyzers in Debug builds: 
    <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <RunAnalyzersDuringBuild>false</RunAnalyzersDuringBuild>
</PropertyGroup>

​
Diagnostic Interpretation

CSENSE016 flags documentation based on several criteria:
  1. Empty or whitespace-only content
  2. Forbidden terms (default: none, configurable)
  3. Too short (default: no minimum, configurable)
  4. Missing capitalization (if require_capitalization = true)
  5. Missing ending punctuation (if require_ending_punctuation = true)
  6. Too similar to member name (if similarity_threshold > 0)
Configuration:
[*.cs]
comment_sense.low_quality_terms = TODO, TBD, FixMe
comment_sense.min_summary_length = 10
comment_sense.require_capitalization = true
comment_sense.require_ending_punctuation = true
comment_sense.similarity_threshold = 0.75
CSENSE012 scans method bodies for explicitly thrown exceptions.Common reasons an exception might not be detected:
  1. Exception is ignored by configuration: 
    [*.cs]
comment_sense.ignored_exceptions = ArgumentNullException
comment_sense.ignore_system_exceptions = true
  2. Exception is thrown in a called method: By default, CommentSense only scans the current method. Enable deep scanning: 
    [*.cs]
comment_sense.scan_called_methods_for_exceptions = true
  3. Exception is thrown indirectly (e.g., via delegates, LINQ, reflection): CommentSense cannot detect all indirect throws. Document these manually.
Symptom: Warning that a cref points to a symbol with lower accessibility.Example:
/// <summary>
/// Uses <see cref="InternalHelper" /> for processing.
/// </summary>
public void Process() { }

internal static class InternalHelper { }
Cause: Public members should not reference internal/private symbols in their public documentation.Solutions:
  1. Change the reference to a public type
  2. Remove the reference if it’s not essential
  3. Suppress the warning if the reference is intentional: 
    #pragma warning disable CSENSE025
/// <summary>
/// Uses <see cref="InternalHelper" /> for processing.
/// </summary>
#pragma warning restore CSENSE025
public void Process() { }

​
Compatibility Issues

CommentSense requires:
  • .NET 5 SDK or later (for DiagnosticSuppressor support)
  • C# 9.0 or later
If you’re using an older SDK:
  1. Upgrade to .NET 5+ SDK
  2. You can still target older frameworks (e.g., <TargetFramework>net48</TargetFramework>)
Yes, as long as you’re using a modern SDK (.NET 5+ SDK).You can target .NET Framework while using the new SDK:
<PropertyGroup>
  <TargetFramework>net48</TargetFramework>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
Yes, CommentSense is a Roslyn analyzer and works in any IDE that supports Roslyn:
  • Visual Studio 2019/2022: Full support
  • JetBrains Rider: Full support
  • VS Code with C# extension: Full support
  • Command line (dotnet build): Full support
Code fixes and Fix All are also supported in all these environments.

​
Getting Help

Check the Rules Reference

See detailed descriptions of all CSENSE diagnostics.

Review Configuration Options

Explore all available .editorconfig settings.

Read Best Practices

Learn recommended patterns for XML documentation.

Report an Issue

If you’ve found a bug, report it on the GitHub repository.

​
Diagnostic Checklist

If you’re experiencing issues, run through this checklist:
1

Installation

  • CommentSense NuGet package is installed
  • <GenerateDocumentationFile>true</GenerateDocumentationFile> is in .csproj
  • Solution builds without errors
2

Configuration

  • .editorconfig exists and is committed to source control
  • .editorconfig syntax is correct (no typos)
  • Configuration options match expected behavior
3

IDE

  • IDE supports Roslyn analyzers
  • Analyzers are enabled in IDE settings
  • IDE has been restarted after installing CommentSense
4

Diagnostics

  • Diagnostics appear in Error List
  • Diagnostic severity is set correctly (warning/error, not none)
  • Suppressed compiler warnings (CS1591, etc.) are hidden
5

Code Fixes

  • Lightbulb appears on diagnostics
  • Code fixes are available in the menu
  • Fix All works as expected

​
Still Having Issues?

If you’ve tried everything and still have problems:
  1. Collect diagnostic information:
    • CommentSense version
    • .NET SDK version (dotnet --version)
    • IDE and version
    • Minimal reproducible example
  2. Search existing issues on the GitHub repository
  3. Open a new issue with:
    • Clear description of the problem
    • Steps to reproduce
    • Expected vs. actual behavior
    • Diagnostic information from step 1
The maintainers and community will help you resolve the issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us