[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Axiom-developer] Executed Examples in documentation ---> Testsuite
From: |
Ralf Hemmecke |
Subject: |
[Axiom-developer] Executed Examples in documentation ---> Testsuite |
Date: |
Mon, 18 Aug 2008 09:24:13 +0200 |
User-agent: |
Thunderbird 2.0.0.16 (X11/20080707) |
Dear Tim,
> there is a new extension to the syntax to add examples. Essentially
> any line that begins with ++E will be output as Example documentation
> to the display command. So the coerce from Tuple now reads:
>
> coerce: PrimitiveArray S -> %
> ++ coerce(a) makes a tuple from primitive array a
> ++
> ++E t1:PrimitiveArray(Integer):= [i for i in 1..10]
> ++E t2:=coerce(t1)$Tuple(Integer)
That seems to be common nowadays. But what if for some reason the output
is wrong? Then the user sees that in the documentation. So, personally,
I would rather add another tag like ++R, for example, that lists the
explicit (expected) output.
Why I think ++R is a good idea, is that the ++E and ++R could be used
for the TestSuite.
You could also move some checking time to the users machine. At the time
the documentation is rendered, the commands in ++E are executed and
compared internally with the ++R stuff.
Since execution might take some time, first show the ++R output and
spawn a background process that compares the output of ++E with ++R.
If that is equal, everything is fine. If it is different. That is a bug.
So notify the user with all the information (about his system) that s/he
should send to a bugtracker.
Just some strange ideas...
Ralf