Thunder.DocSnippets 0.1.0-preview7

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="Thunder.DocSnippets" Version="..." />

Quick start

1. Add DocSnippets to your test project:

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

2. Run dotnet test. Done.

DocSnippets ships an MSBuild .targets file that automatically wires up the adjacent source project's .cs files as AdditionalFiles — no manual <ItemGroup> configuration required.

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.

Excluding a snippet

Add // doctest-ignore on the first line of any <code> block to skip it:

/// <code>
/// // doctest-ignore
/// // This example is illustrative — not executable.
/// var x = SomeExternalCall();
/// </code>

Configuration (docsnippets.json)

Add a docsnippets.json file alongside the source files (it is picked up automatically as an AdditionalFile by the shipped MSBuild targets) 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-preview6

• #line diagnostics — build errors in generated test methods now point to the original source line, not the generated file
• 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