Thunder.DocSnippets 0.1.0-preview6

DocSnippets

Make your C# XML doc <code> examples runnable as unit tests — the Rust doctest experience for .NET.

DocSnippets is a Roslyn source generator. Add the package, and every <code> block in your XML documentation becomes a compiled, executable NUnit/xUnit/MSTest test method. No extra tooling, no checked-in generated files.

<PackageReference Include="DocSnippets" Version="..." />

Quick start

1. Add DocSnippets to your test project:

   <PackageReference Include="DocSnippets" Version="..." />
   

2. Add your source project's .cs files as AdditionalFiles:

   <ItemGroup>
     <AdditionalFiles Include="../MyLib/**/*.cs" Exclude="../MyLib/obj/**;../MyLib/bin/**" />
   </ItemGroup>
   

3. Run dotnet test. DocSnippets generates a test class for each source file that contains <code> blocks. Each snippet becomes a [Test] / [Fact] / [TestMethod].

Writing snippets

Any <code> block in an XML doc comment is picked up automatically:

/// <summary>Adds two integers.</summary>
/// <example>
/// <code>
/// var result = calculator.Add(1, 2); // => 3
/// </code>
/// </example>
public int Add(int a, int b) => a + b;

The // => 3 assertion is transformed into a framework-appropriate equality check at generation time. No assertion library is required in the snippet itself.

Configuration (docsnippets.json)

Add docsnippets.json as an AdditionalFile alongside your source files to configure the generator:

{
  "snippetMode": "opt-out",
  "assertionStyle": "NUnit",
  "implicitUsings": ["MyLib", "MyLib.Models"]
}

Opt-in mode

Mark individual snippets with // doctest to include them when snippetMode is "opt-in":

/// <code>
/// // doctest
/// var x = Multiply(3, 4); // => 12
/// </code>

InternalsVisibleTo

If your snippets reference internal types, add this to your source project:

[assembly: InternalsVisibleTo("YourTestProject")]

Without it, snippets referencing internal members produce CS0122 errors that can be hard to diagnose.

What's new in v0.1.0-preview5.7

• assertionStyle config override — override auto-detected framework via docsnippets.json
• //=> arrow alias — //=> accepted as shorthand for // =>
• Assert value in test method name — Add_ShouldBe_3 naming from // => assertions
• Overload disambiguation — param-type suffix on overloaded method test names
• Operator and destructor name sanitization — valid C# identifiers for operator +, ~MyClass, etc.
• snippetMode: opt-in — only run explicitly marked snippets
• MSBuild auto-wiring — AdditionalFiles glob injected via shipped .targets file