[example-main]: http://idldatapoint.com/2012/05/03/the-merits-of-an-example-main-program “IDL Data Point: The merits of an example main program”
[doctest]: http://docs.python.org/library/doctest.html “Python doctest module”
The IDL Data Point recently had an [article][example-main] about writing a simple main-level program at the bottom of each file which would give an example or test of the routine(s) in the files. I like this idea and have been doing it for quite a while, but one of the annoyances of this approach is that I also typically want the code to be included in the documentation for the routine, so I end up copy-and-pasting the code into the examples section of the docs (and, of course, reformatting it for the doc syntax). Also, the main-level program just is a place to put some code, I have to do all the work if I actually want to write multiple pass/fail tests.
For example, Python’s [doctest module][doctest] provides a solution to these problems for Python. In your docs, you give a command and its expected output:
>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
Then, in the main-level program, you say something like (I’ve omitted some Python details for simplicity here):
When you do the equivalent of running the main-level program, the docs are checked for “>>>” lines which are executed and compared to the output shown in the docs.
It seems like there are several solutions that could be implemented in IDLdoc or mgunit to solve this problem.
1. Create a `doctest` routine for IDL. This would mean to create a routine like the `dockets.testmod()` routine in `doctest` that runs all the lines in the documentation that begin with “IDL>” and compares the results to the output shown below the “IDL>” line.
*Advantages:* Can be used to easily run tests and compare results to provided output. Test commands and output are included in documentation, but are not present twice in the file.
2. Conversely, create an IDLdoc `include` directive, like `..include:: [main-level]` that includes the contents of the main-level of the current file. This could be used in the examples section of the docs to include the main-level program.
*Advantages:* Could also be used to include other files which might be useful in other situations.
*Disadvantages:* For files with multiple routines in a file, the entire main-level program would be included at the location, even if the main-level program addressed multiple of the routines. Doesn’t help with testing.
3. Allow IDLdoc to do the testing by creating a tests section that would be executed when IDLdoc is run.
*Advantages:* Can be used to easily run tests and compare results to provided output. Test results appear in the IDLdoc output.
*Disadvantages:* Need to run IDLdoc to run the tests.
Once nice thing here is that several of these strategies could be implemented. Any ideas, suggestions on what you would like to see? Creating an `MG_DOCTEST` routine seems like the strongest solution right now, but am I missing something?