Re: [pdf-devel] torture utils and test data files: Comment format

[gerel]

 > Date: Tue, 06 Jan 2009 17:52:00 +0100
 > From: address@hidden
 > 
 >    Jemarch, if you agree I'm willing to automatize the unit testing
 >    documentation process.
 > 
 > I agree. It will prevent us to duplicate work documenting the tests.
 > 
 >    The idea would be to follow two rules:
 > 
 >    1. Define a format for the comments for each test procedure in the unit 
 > test
 >       files (the one used right now I guess is OK but I'm not sure if it's 
 > the
 >       one used for _every_ test file).
 > 
 > The current format should be currently used in every test file, but it
 > would need to be extended to support an easily-parseable list of used
 > data files. Can you send a proposal to the list?

BTW, I don't really want to define a very strict format, it will be tedious to
use and to parse, I'll rather try to adapt the parser to the format already
used.

So, after reading some tests, I think the following format is fine:
/*
 * Test: newline* <name> newline*
 * Description: newline* <description> newline*
 * Success condition[s]: newline* <cond 1> [newline+ <cond X>...] newline*
 * [Data file[s]: newline* <file 1> [<file X>...] newline*]
 */

Where newline*/+ means zero/one or more new lines.
Notice that in case of success conditions the newlines are meaningful, they
separate each condition.
For data files since the name format is very strict 'TDXXXXX' we can use any
non-alphanumeric character as separator.
Summarizing, the truly important part is the beginning string "Test:" that can
be found after any number of spaces/newlines.

Anyways, that's it.

cheers
-gerel