develooper Front page | perl.perl5.porters | Postings from December 2000

RE: =code language ... =back in POD

Thread Previous | Thread Next
From:
Paul Marquess
Date:
December 13, 2000 14:40
Subject:
RE: =code language ... =back in POD
Message ID:
001c01c06506$bbc47f00$a20a140a@bfs.phone.com
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.com


Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About