APIs and Doctesting

So my student and I (alright my student), are writing a Python version of the Ensembl API as a Google Summer of Code project. She's at a decision point that will require some head-scratching so while that is going on, we're going to do some testing.

My previous place of employment had created an API for this home-grown LIMS system, both of which were written in Perl. They created lots of documentation using POD and included examples of how to use the methods. The problem was that the examples quickly became outdated with new releases and were of ultra-low priority compared to delivering new features.

I was showing my student a bit of how doctests can accomplish this very thing, but because they act as automated tests, they can be kept up-to-date more easily because it's easy to know if they ever become broken. Those who work with doctests have known this for a long time, but I marvel at the match made in heaven when it comes to writing an API. I heart you Python Doctests.