Thunder.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 to your test project, and every <code> block in your library's XML documentation becomes a compiled, executable NUnit/xUnit/MSTest test. No extra tooling, no checked-in generated files.

---

Quick start

1. Add DocSnippets to your test project (.Tests.csproj or similar):

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

2. Run dotnet test. Done.

DocSnippets automatically picks up the adjacent source project's .cs files via its shipped MSBuild .targets file — no manual <AdditionalFiles> configuration required.

---

Writing snippets

Any <code> block in an XML doc comment is picked up automatically in opt-out mode (the default):

/// <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 becomes a framework-appropriate equality check at generation time. No assertion library is needed 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>

Opt-in mode

By default all blocks run. To run only explicitly marked blocks, add docsnippets.json to the adjacent source project and set snippetMode to "opt-in", then mark each runnable snippet with // doctest:

/// <code>
/// // doctest
/// var result = calculator.Add(1, 2); // => 3
/// </code>

---

Configuration (docsnippets.json)

Drop a docsnippets.json file alongside the source files:

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

Key	Values	Default	Description
snippetMode	"opt-out", "opt-in"	"opt-out"	opt-out: all <code> blocks run. opt-in: only blocks marked // doctest run.
assertionStyle	"NUnit", "XUnit", "MSTest"	(auto-detect)	Override the auto-detected test framework.
implicitUsings	Array of namespace strings	[]	Namespaces added as using to every generated test class.

---

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.

---

Documentation

Full docs at docs.thundersizzle.tech/public/Thunder/thunder-docsnippets/.

---

Licence

MIT — see LICENCE.