Myrna van Lunteren wrote:
Hi,
I've been wondering and worrying about our doc examples.
Before contribution to apache, we did a couple of passes to test and
verify all doc examples. But this is a very time-consuming and
error-prone process for various reasons: easy for an individual to
miss a snippet, snippets are not written with tests in mind and don't
easily follow on each other and so every snippet needs to have a
separate test written...or get tested manually...
Also examples continue to get changed and for new code we should get
new examples, and we now have a demo database (toursdb) that we
probably should try to use...And I don't see that anyone has time
available to test all the snippets.
I think we should have automated tests for the doc examples.
Or at least as many as possible.
I am thinking, it should be possible to extract the example code from
the dita files and automatically build tests based on it.
We could mark the snippets that are easy to be wrapped into an SQL
examples one way, java snippets another, full java classes yet
another, extract them, and refresh the tests that way...(nightly?
monthly? at code freeze dates?)
Maybe add a specific string to each example so we can search the dita
files for that. Or maybe there already is a specific sort of
property/tag for code snippets?
This also has implications for the examples - they should be
(re)written with wrapping into a test in mind.
Does this seem doable/feasible/sensible?
Myrna
+1. Would be really useful.
With the toursdb demo availabe in the codeline, I think all the queries
should work as is. A great deal of attention needs to be paid
to the results returned by the sample queries. I noticed, for ex.
DERBY-994, LEFT/RIGHT OUTER JOIN examples, the queries worked just fine
- but
the results and description did not make sense at all.
-Rajesh
