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
_______________________________________________
Axiom-developer mailing list
[email protected]
http://lists.nongnu.org/mailman/listinfo/axiom-developer
