Automatically Unit Test Example Code

Question

My team is responsible for the development of an API for a large system that we also write. We need to provide example code so that other developers using our API can learn

Answer 1

I would suggest using a special bit of markup in your XML which says, "Grab the code sample from this place". It would refer to a normal C# file which can be run with unit tests. To take your example, you might have:

/// 
Summary here
/// Here is an example
/// !!sourcefile:SomeClassTest.cs#SomeFunction!!
public void SomeFunction()

Your unit tests run as normal, and then insert a build step between "create XML" and "run Sandcastle" you'd replace each "file token" with the appropriate contents. There may even be hooks you could put into Sandcastle to do this at doc generation time - I don't know enough about Sandcastle to know for sure.

It's ugly to invent your own markup of course, but it should work.

Of course, this assumes that the code examples are easily unit testable - some may not be (if they're dealing with resources etc). At least you'd know it compiles though :)