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

Yes, sandcastle supports this and it's great to maintain the correctness of examples. You can point to a code region like this:

   /// 

   /// Gizmo which can act as client or server.
   /// 
   /// 
   /// The following example shows how to use the gizmo as a client:
   /// 
   /// 
   public class Gizmo

You can then use some test code in TestGizmo.cs as an example by enclosing it in a region:

[Test]
public GizmoCanActAsClient()
{
   #region GizmoClientSample
   Gizmo gizmo = new Gizmo();
   gizmo.ActAsClient();
   #endregion
}

Caveat: If you move or rename the test file, you will only get an error about this when you try to regenerate the documentation with sandcastle.