[Bug 1549] It must be easier to write tests

[bugzilla-daemon at rtems.org]

https://www.rtems.org/bugzilla/show_bug.cgi?id=1549





--- Comment #4 from Sebastian Huber <sebastian.huber at embedded-brains.de>  2010-06-11 02:27:21 ---
> --- Comment #2 from Chris Johns <chrisj at rtems.org>  2010-06-10 20:35:49 ---
>> 1. An extra directory for each test case is not needed.  We can use different
>> file prefixes for each test case.
> 
> That is true but all files in one directory is not such a great idea either.

Grouping by directory or file name prefix is not that different.

>> 4. The *.doc files are pretty useless in the current format.  We should define
>> guidelines how do to document tests.  We should write them in a machine and
>> human readable form.  I propose Doxygen.  If someone does not like Doxygen it
>> is trivial to write a parser that transforms the Doxygen comments into
>> something else.
> 
> I support doxygen as an internal software documentation tool how-ever I am
> currently not convinced about using it for formal external documentation. We
> already have a documentation format, texinfo. 

Yes, we have the texinfo files.  Compare the update frequency of the source
code path with the documentation tree.  It is a constant burden to keep this
synchronized.  Only few people touch the texinfo files at all.  We should move
to source code embedded documentation (e.g. Doxygen) entirely.  You can write
book style documentation with Doxygen easily.  See

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpage

> Can the test docs be written in texinfo format and included from a top level
> document in the current doc tree to create a test document ? The upside here is
> the ability to include this in the current manuals, daily documentation build
> etc without needing to include a new standard, tool or custom filter script.

I guess that you have to edit the top level document each time you add a new
test.  This makes it even more complicated.

The real problem are all the different files and locations.  We have to reduce
this.  We can specify a special comment format for tests and add the test
documentation directly to the test source code.  We may use Doxygen for this. 
If someone doesn't like the Doxygen generated stuff, we can write a format
converter.

We need a formal test documentation specification.

[...]

-- 
Configure bugmail: https://www.rtems.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching all bug changes.