Skip to main content

​
Overview

This guide will walk you through installing CommentSense, configuring your project, and experiencing the core features including diagnostics and automatic code fixes.
This quick start assumes you have a C# project using .NET 8.0 or later. CommentSense works with any .NET project that supports Roslyn analyzers.

​
Step 1: Install CommentSense

First, add the CommentSense NuGet package to your project: 
dotnet add package CommentSense

​
Step 2: Enable XML Documentation

CommentSense requires XML documentation generation to analyze your code. Add this to your .csproj file:
YourProject.csproj
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="CommentSense" Version="*" />
  </ItemGroup>
</Project>
If you skip this step, CommentSense will report CSENSE000 warning and cannot analyze your documentation.

​
Step 3: Create a Sample Class

Let’s create a simple C# class to see CommentSense in action. Create a new file called Calculator.cs:
Calculator.cs
public class Calculator
{
    public int Add(int a, int b)
    {
        return a + b;
    }

    public int Divide(int numerator, int denominator)
    {
        if (denominator == 0)
            throw new ArgumentException("Cannot divide by zero");
            
        return numerator / denominator;
    }
}

​
Step 4: Build and See Diagnostics

Build your project to see CommentSense diagnostics: 
dotnet build
You should see several warnings:
1

CSENSE001: Missing documentation on Calculator class

The public class has no XML documentation.
2

CSENSE001: Missing documentation on Add method

The public method has no XML documentation.
3

CSENSE001: Missing documentation on Divide method

The public method has no XML documentation.
In your IDE (Visual Studio, VS Code, or Rider), you’ll see these as squiggles under the member names with light bulb icons offering code fixes.

​
Step 5: Apply Automatic Code Fixes

CommentSense provides automatic code fixes for most diagnostics. Let’s add documentation to the Calculator class:

​
Using Visual Studio or Rider

  1. Click on the Calculator class name
  2. Press Ctrl+. (or click the light bulb icon)
  3. Select “Add missing documentation”
  4. The code fix will generate a placeholder <summary> tag

​
Using VS Code

  1. Click on the Calculator class name
  2. Press Ctrl+. or Cmd+. (or click the light bulb)
  3. Select “Add missing documentation”

​
Result

The code fix will generate:
Calculator.cs
/// <summary>
/// TODO: Add summary
/// </summary>
public class Calculator
{
    public int Add(int a, int b)
    {
        return a + b;
    }

    public int Divide(int numerator, int denominator)
    {
        if (denominator == 0)
            throw new ArgumentException("Cannot divide by zero");
            
        return numerator / denominator;
    }
}
Code fixes support Fix All in Document, Project, or Solution scope. Right-click the light bulb and select “Fix All occurrences in…” to apply fixes to multiple members at once.

​
Step 6: Write Meaningful Documentation

Replace the placeholders with meaningful documentation:
Calculator.cs
/// <summary>
/// Provides basic arithmetic operations.
/// </summary>
public class Calculator
{
    /// <summary>
    /// Adds two integers and returns the result.
    /// </summary>
    /// <param name="a">The first number to add.</param>
    /// <param name="b">The second number to add.</param>
    /// <returns>The sum of the two numbers.</returns>
    public int Add(int a, int b)
    {
        return a + b;
    }

    /// <summary>
    /// Divides one integer by another.
    /// </summary>
    /// <param name="numerator">The number to be divided.</param>
    /// <param name="denominator">The number to divide by.</param>
    /// <returns>The quotient of the division.</returns>
    /// <exception cref="ArgumentException">Thrown when denominator is zero.</exception>
    public int Divide(int numerator, int denominator)
    {
        if (denominator == 0)
            throw new ArgumentException("Cannot divide by zero");
            
        return numerator / denominator;
    }
}

​
Step 7: Experience Quality Analysis

CommentSense doesn’t just check for missing documentation - it also validates quality. Let’s see this in action:
Example.cs
public class Example
{
    /// <summary>MyProperty</summary>
    public string MyProperty { get; set; }
}
This will trigger CSENSE016 because the documentation just repeats the member name. CommentSense can detect:
  • Empty or whitespace-only documentation
  • Documentation that repeats the member name
  • Missing capitalization
  • Missing ending punctuation
  • Low-quality placeholder terms like “TODO” or “TBD”
The automatic code fix can correct capitalization and punctuation:
Example.cs
public class Example
{
    /// <summary>Gets or sets the property value.</summary>
    public string MyProperty { get; set; }
}

​
Step 8: See Exception Tracking

Notice how CommentSense detected the ArgumentException in the Divide method? Let’s explore this feature:
Validator.cs
/// <summary>
/// Validates user input.
/// </summary>
public class Validator
{
    /// <summary>
    /// Validates that a string is not null or empty.
    /// </summary>
    /// <param name="value">The string to validate.</param>
    public void ValidateNotEmpty(string value)
    {
        if (string.IsNullOrEmpty(value))
            throw new ArgumentNullException(nameof(value));
            
        ArgumentNullException.ThrowIfNull(value);
    }
}
This code will trigger CSENSE012 for the missing <exception> tag. CommentSense scans method bodies for:
  • Explicit throw statements
  • Guard clause methods like ArgumentNullException.ThrowIfNull
  • Optionally, exceptions documented in called methods (when configured)
Apply the code fix to add the missing exception documentation:
Validator.cs
/// <summary>
/// Validates user input.
/// </summary>
public class Validator
{
    /// <summary>
    /// Validates that a string is not null or empty.
    /// </summary>
    /// <param name="value">The string to validate.</param>
    /// <exception cref="ArgumentNullException">TODO: Add exception description</exception>
    public void ValidateNotEmpty(string value)
    {
        if (string.IsNullOrEmpty(value))
            throw new ArgumentNullException(nameof(value));
            
        ArgumentNullException.ThrowIfNull(value);
    }
}

​
Step 9: Explore Additional Features

CommentSense includes many more features:

​
Parameter Reference Detection (CSENSE020)

/// <summary>
/// Processes the name parameter.
/// </summary>
public void Process(string name) { }
This triggers CSENSE020 because “name” should be wrapped in <paramref name="name" />. The code fix automatically wraps it: 
/// <summary>
/// Processes the <paramref name="name" /> parameter.
/// </summary>
public void Process(string name) { }

​
Keyword Detection (CSENSE019)

/// <summary>
/// Returns true if valid, false otherwise.
/// </summary>
public bool Validate() { return true; }
This triggers CSENSE019 because true and false should use <see langword="..." />. The code fix corrects it: 
/// <summary>
/// Returns <see langword="true" /> if valid, <see langword="false" /> otherwise.
/// </summary>
public bool Validate() { return true; }

​
Tag Ordering (CSENSE024)

/// <returns>The result.</returns>
/// <summary>Calculates something.</summary>
/// <param name="x">Input value.</param>
public int Calculate(int x) { return x; }
This triggers CSENSE024 because tags are not in the standard order. The code fix reorders them: 
/// <summary>Calculates something.</summary>
/// <param name="x">Input value.</param>
/// <returns>The result.</returns>
public int Calculate(int x) { return x; }

​
Step 10: Customize with Configuration

Create an .editorconfig file in your project root to customize CommentSense behavior:
.editorconfig
root = true

[*.cs]
# Analyze all members down to internal visibility
comment_sense.visibility_level = internal

# Require summaries to be at least 15 characters
comment_sense.min_summary_length = 15

# Detect documentation similar to member names
comment_sense.similarity_threshold = 0.8

# Add custom low-quality terms
comment_sense.low_quality_terms = TODO, TBD, FixMe, WIP

# Exclude constants from documentation requirements
comment_sense.exclude_constants = true
See the Configuration Guide for all available options and detailed explanations.

​
Common Workflows

​
Fix All Documentation Issues in a File

  1. Open a file with multiple CommentSense warnings
  2. Press Ctrl+. on any diagnostic
  3. Select “Fix All occurrences in Document”
  4. CommentSense will add placeholder documentation for all members
  5. Replace placeholders with meaningful descriptions

​
Fix All Documentation Issues in a Project

  1. Right-click any CommentSense diagnostic in the Error List
  2. Select “Fix All occurrences in Project”
  3. Review and update generated placeholders

​
Suppress Specific Rules

If you want to disable specific rules, add this to your .editorconfig:
.editorconfig
[*.cs]
# Disable low-quality documentation checks
dotnet_diagnostic.CSENSE016.severity = none

# Disable exception documentation requirements
dotnet_diagnostic.CSENSE012.severity = none

​
What’s Next?

Configuration

Learn how to customize CommentSense behavior for your project

Rules Reference

Explore all 26 diagnostic rules and their options

Best Practices

Learn tips and patterns for writing excellent documentation

Troubleshooting

Solutions to common issues and questions

​
Summary

You’ve now experienced the core features of CommentSense:
Installed CommentSense via NuGet
Enabled XML documentation generation
Saw diagnostics for missing and low-quality documentation
Applied automatic code fixes
Experienced quality analysis, exception tracking, and reference detection
Learned how to configure CommentSense via .editorconfig
CommentSense will now continuously analyze your code as you write, helping you maintain high-quality API documentation across your entire codebase.

Build docs developers (and LLMs) love

Get started for freeTalk to us