Thunder.DocSnippets 0.1.0

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 assertion comment is transformed into a framework-appropriate equality check at generation time. No assertion library is required in the snippet itself.

Inline assertion patterns

All four comment styles work on both declaration lines and expression lines:

On a declaration line (var x = f(); // => 3), the generator splits the line into the declaration statement and a separate assertion using the declared variable name. On an expression line (f(); // => 3), the entire expression becomes the assertion subject.

Bare literal comments (// 42, // true, // "hello") are only treated as assertions when the comment contains an unambiguous C# literal. Non-literal comments (// sum of values, // see above) are left unchanged.

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.

Known limitations

• Tuple deconstruction — var (a, b) = f(); // => ... is not supported. Use a separate assertion line.
• Async snippets — snippets containing await are not supported. The emitted test method is synchronous; await will produce a compile error.
• Single-assembly scanning — only direct ProjectReference source projects are scanned. Transitive references are not.

What's in v0.1.0

• Inline assertion patterns — four comment styles on both declaration and expression lines: // => VALUE, // result: VALUE, // VARNAME: VALUE, bare literal // 42
• #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