Build Documentation from your Tests

A couple months ago I decided to toy around with some code ideas in my head. I had two goals:

  1. To be able to parse some plain English and make DateTime and Timespans objects.
  2. To try out Parsley (because I have a not-so-secret urge to write a language)

After a quick spike a while back I had something I named TempusReader, working code which I posted on Github. I don’t think something like Parsley was absolutely necessary for me to do what I wanted, but most importantly, I was able to acheive both of my goals.

While working on this code, I wanted to provide documentation on how to use it. In my experience, looking at tests is one good way to understand how something works. The odds of somebody looking in a test file are slim, but looking at the readme file are almost necessary when visiting a page on github.

I could just output some text to my readme files directly from my tests, right? This was actually a fun little task and potentially quite helpful. I’d like to explore this area more in the future, maybe a simple file to pull from Nuget, configure, then be off to the races. It’s pretty raw as it sits, but I thought I’d share the idea.

Here is the file that’s doing the work:

https://github.com/ChrisMissal/TempusReader/blob/master/src/Tests/DocumentationBuilder.cs

 

Related:

Post Footer automatically generated by Add Post Footer Plugin for wordpress.

About Chris Missal

Oh hey, I'm a Senior Consultant for Headspring in Austin, TX. I've been working in software professionally since 2006 and I really, really love it. I'm mostly in the Microsoft world, but enjoy building computer things of all sorts (to be vague). When I'm not slinging code, I'm probably out and about slinging discs, bowling balls, or good beer with great friends.
This entry was posted in .NET, Open Source and tagged , . Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Jasper

    I think self-documenting systems are a fantastic idea.  I look forward to the day when documentation has no choice but to be up-to-date :)

  • http://adamralph.myopenid.com/ Adam Ralph

    You might be interested in https://nuget.org/packages/Xbehave (biased recommendation – I am the author).

    When running a test suite written using xBehave.net using the xunit console, the test output reads like a complete specification (documentation) of the target.

  • http://adamralph.myopenid.com/ Adam Ralph

    You may be interested in xBehave(dot)net (https://nuget.org/packages/Xbehave). Note – this is a biased recommendation – I am the author of the library.

    When running a test suite written using xBehave(dot)net, the output from the xUnit(dot)net console runner reads like a specification (documentation) of the target, e.g. http://teamcity.codebetter.com/repository/download/bt635/50272:id/Xbehave.Test.Acceptance.Net40/bin/Debug/XBehave.Test.Acceptance.Results.html.

    This is the standard output from the xUnit(dot)net console runner, no special action required.