[E-Lang] Announcing Updoc
Mark S. Miller
Mon, 16 Jul 2001 17:07:30 -0700
At 3/29/01, Tyler Close wrote:
>> but one thing I've really become a big fan of
>> lately is automated unit tests, where those tests are
>> meant, in a very real
>> sense, to be an effective "executable spec" for the code
>> (but not in the usual way that term is applied).
>When you say it like this, it reminds me that this is what updoc is
>for. MarkM, I couldn't find anything on the erights.org site about
>updoc. Are there any examples of how to use it?
There are now: http://www.erights.org/elang/tools/updoc.html . This page is
both an explanation of Updoc and an example Updoc script.
My wife Terry ( http://www.cocoon.com ) and I recently read about pair
programming and (a bit about) Extreme Programming, so we decided to pair
program the revival of CapTP (the old "proxy comm system"). Part of this
methodology is supposed to be the constant creation of test cases while
programming, so we found we needed an answer to Dan's and Tyler's question
We pulled the Updoc idea from the shelf, completed it, and have started
using it. Besides using on the revival of CapTP itself, the erights.org web
site was already a tremendous potential regression test for E, as all the
embedded code examples were already written in the format expected by Updoc,
in anticipation of having an Updoc to run them through.
Well, with three years of history without such a tool, the web site doesn't
yet pass. The result of bringing it into closer conformance has not only
caused many bugs in the documentation to be fixed, it has caused many
annoyances and one serious bug in E to be identified and fixed.
The serious bug? As a result of the new E-to-Java overload resolution
mechanisms, "2.3 < 3.4" was throwing an exception complaining about an
ambiguous overload. While this is terribly broken, it wasn't caught by our
usage of E, since we don't actually use floating point for anything.
It will be a while before the entire web site passes. But once it does, it
should be easy to maintain it's accuracy, while also using it to check E's
correctness. In the meantime, the list of pages that contain test cases and
currently pass are:
Each of the dots after the URL indicate a passing test case.
Updoc has had a long history, starting at Agorics as part of the
Tclio/Webmart project, maybe 5 or 6 years ago. I remember Bill Frantz and I
working on the idea back then, and again at Electric Communities. No doubt
there were other contributions at both companies I'm failing to acknowledge.
At EC, Brian Marick contributed insights (briefly explained on the Updoc
page) about how Updoc may address some of the traditional problems with
regression testing. The current Updoc, to be part of the 0.8.10 release, is
by Terry Stanley and Mark Miller.
And now, back to CapTP...