CommentsExtractor.RuntimeDependencies 26.1.63689

CommentExtractor Source Generator

A Roslyn-based source code generator for C# (.NET 10) that extracts XML documentation comments from public methods and properties at compile time and makes them available at runtime.

Features

• Automatic Extraction: Automatically finds all classes annotated with [ExtractComments].
• Public Member Support: Extracts triple-slash (///) XML documentation for all public methods and properties.
• Overload Support: Correctly handles method overloads, allowing you to retrieve all matching comments by member name.
• Unique Identification: Generates unique constant names for each member, including parameter types for methods to ensure no collisions.
• Efficient Retrieval: Provides a static CommentRegistry.GetComments method lookup.

Project Structure

• CommentExtractor.Attributes: Contains the [ExtractComments] attribute.
• CommentExtractor.Generator: The Roslyn Incremental Source Generator.
• CommentExtractor.Tests: A sample project demonstrating usage and verification.

Setup

1. Reference the Attributes and Generator: In your project file (.csproj), add the following:

   <ItemGroup>
     <PackageReference Include="CommentExtractor" Version="*"
                       OutputItemType="Analyzer" 
                       ReferenceOutputAssembly="false" />
   </ItemGroup>
   

2. Enable XML Documentation: The generator relies on the compiler's XML documentation extraction. You must enable it in your .csproj:

   <PropertyGroup>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   
     <NoWarn>$(NoWarn);CS1591</NoWarn>
   </PropertyGroup>
   

Usage

1. Annotate your class

using CommentExtractor.Attributes;

namespace MyNamespace;

[ExtractComments]
public class MyService
{
    /// <summary>
    /// This is a sample method.
    /// </summary>
    /// <param name="id">The identifier.</param>
    public void DoWork(int id) { }

    /// <summary>
    /// Gets or sets the name.
    /// </summary>
    public string Name { get; set; }
}

2. Retrieve comments at runtime

Use the CommentRegistry class (located in the CommentExtractor.Attributes namespace):

using CommentExtractor.Attributes;

string[] comments = CommentRegistry.GetComments("MyNamespace.MyService", "DoWork");

foreach (var comment in comments)
{
    Console.WriteLine(comment);
}

How it works

The generator scans for classes marked with [ExtractComments]. For each such class, it iterates through all public methods and properties. It then:

1. Extracts the XML documentation string using Roslyn's GetDocumentationCommentXml().
2. Generates a private constant string containing the XML.
3. Populates a static dictionary mapping (FullTypeName, MemberName) to an array of these constants.

This allows for extremely fast retrieval of documentation at runtime without using heavy Reflection or parsing XML files manually.