Introduction

​

What is CommentSense?

​

Key Features

​

Why CommentSense?

• Quality Analysis: Ensure documentation is meaningful, not just present
• Exception Tracking: Automatically detect thrown exceptions and ensure they’re documented
• Smart References: Flag parameter and keyword references that should use proper XML tags
• Consistency Checks: Enforce tag ordering, proper use of <inheritdoc />, and more
• Automatic Suppression: Replaces overlapping C# compiler warnings to reduce noise

​

Documentation Rules Overview

​

General Documentation

• CSENSE001: Missing XML documentation on public members
• CSENSE016: Low-quality documentation detection
• CSENSE007: Invalid cref attribute validation
• CSENSE019: C# keyword recommendations for <see langword="..." />
• CSENSE024: XML documentation tag ordering

​

Parameters & Type Parameters

• CSENSE002/004: Missing parameter or type parameter documentation
• CSENSE003/005: Stray parameter tags
• CSENSE008/010: Parameter ordering enforcement
• CSENSE020/021: Ghost reference detection (unwrapped parameter names)

​

Return Values & Exceptions

• CSENSE006: Missing <returns> tags
• CSENSE012: Missing exception documentation with body scanning
• CSENSE017: Exception type validation

​

Properties

• CSENSE014: Optional <value> tag requirements
• CSENSE015: Stray <value> tags

​

Getting Started

​

Requirements

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

​

Example

// ❌ Missing documentation - CSENSE001
public class MyClass
{
    // ❌ Low quality documentation - CSENSE016  
    /// <summary>MyMethod</summary>
    public void MyMethod(string name)
    {
        // ❌ Missing exception documentation - CSENSE012
        throw new ArgumentNullException(nameof(name));
    }
}

/// <summary>Represents a custom class for demonstration.</summary>
public class MyClass
{
    /// <summary>Processes the provided name parameter.</summary>
    /// <param name="name">The name to process.</param>
    /// <exception cref="ArgumentNullException">Thrown when name is null.</exception>
    public void MyMethod(string name)
    {
        throw new ArgumentNullException(nameof(name));
    }
}

​

Next Steps