Front page | perl.perl5.porters |
Postings from December 2000
From: Tels [mailto:perl_dummy@bloodgate.com] > Moin, > > On 12-Dec-00 Jarkko Hietaniemi tried to scribble about: > > In the ideal case one would also be able to specify the input (command > > line arguments, input files, etc) and the expected output. > > Only if the example is actually run. But I intend to check the syntax > (compilable), not the input/output (runnable). > > Me thinks examples are to give syntax, not actually runnable code (except > for really big examples). Very often the setup etc is missing in the > examples, whic is ok by me, but makes them unrunnable, anway. > > What I really like about Perl are the testcases, that prevent old > bugs from > cropping up again. For the doc, this is missing, every change in the code > (api!) or the doc can outdate the doc or invalid it. Would be cool if > authors had an automated test-tool that quick-checks the examples in the > doc for syntax errors. ;) For the BerkeleyDB module I created a very simple pre-processor that allowed me to extract arbitrary sections of code from my test harness files and merge them into the pod documentation. Sections of code are bracketed in the test harness files with ##BEGIN and ##END markers like this: ##BEGIN some_label my $secs_per_hour my $secs_per_day = secs_per_hour * 24 ; ##END some_label ($secs_per_day == 86400) ? "ok 1\n" : "not ok 1\n" ; and then the pod file will reference code snippets by referring to its "label" thus: =head1 INTRODUCTION Here is some code to work out the number of seconds in a day. ##some_label ... Having this in place allows me to check the example code in my pod file with the all the versions of Berkeley DB that are available -- I have another script that checks that all combinations of Perl > 5.00404 work with all versions of Berkeley DB > 2.0. It was a bit of work to set up, but I feel it was worth the effort. Paul _________________________________________________________ Do You Yahoo!? Get your free @yahoo.com address at http://mail.yahoo.comThread Previous | Thread Next