[Canberra-pm] Podding around

Paul Matthews plm at netspace.net.au
Tue Jul 29 16:54:40 PDT 2008


G'day all,

Somebody at work is somewhat intent on using pod's to document code. 
(You know who you are). I mean 300 programs and libraries and 30,000 
lines of perl code in production ... ha ... documentation is for the 
weak ...

So I took a simple module which contains multiple packages (objects) and 
tried to pod it. At the start all was going well. podchecker was happy 
and pod2text was producing sensible output. However when fed into 
pod2html, it all got a little strange.

Now if you look at the below example you will no doubt conclude I have 
little idea what I was doing. That is because although there is a page 
detailing what the pod instructions are, it does not describe how to use 
them to build a working html document. Especially not one with multiple 
objects.

If the below is compiled with pod2text it looks cool. With pod2html all 
the =head1's with the exception of the first are not generated at all. 
Any hints would be appreciated. (Code removed and names changed to 
protect the guilty.)

BTW: I have not run it thru pod2projectdocs, mostly cause I'm at home 
sick and there is no obvious OpenSuSE rpm for it.

PS: Has anyone used NaturalDocs. I have been thinking we could use pod 
to create the external usage / manual for the program / library after 
the __END__, and NaturalDocs to spit out all the internal implementation 
documentation.


=head1 NAME

dbs.pm

=head2 DESCRIPTION

Objects holding the information and structure of the databases.

=cut


=head1 NAME

dbbase

=head2 DESCRIPTION

Base class of all db objects. This class should never be directly
instantiated.

=head2 SYNOPSIS

$base = new dbbase;
$name = $base->set_name($name);
$name = $base->get_name($name);
$date = $base->set_create_date($date);
$date = $base->get_create_date();
$user = $base->set_last_user($user);
$user = $base->get_last_user();
$date = $base->set_last_update_date($date);
$date = $base->get_last_update_date();
$vers = $base->set_last_version($vers);
$vers = $base->get_last_version();

=cut


=head1 NAME

dbelement

=head2 DESCRIPTION

Information concerning dbelements.

=head2 SYNOPSIS

$elem  = new dbelement;
\@desc = $elem->set_desc(@desc);
\@desc = $elem->get_desce();
         $elem->add_desc($desce);

=head2 SEE ALSO

L<dbbase>

=cut


=head1 NAME

dbthing

=head2 DESCRIPTION

Base class for both dbfield's and dbimage's. This class never be directly
instantiated, only indirectly via the dbfield and dbimage class.

=head2 SYNOPSIS

$len   = $thing->set_length($len);
$len   = $thing->get_length();
$type  = $thing->set_type($type);
$type  = $thing->get_type();
$fmt   = $thing->set_format($fmt);
$fmt   = $thing->get_format();
$elem  = $thing->set_element($elem);
$elem  = $thing->get_element();
\@desc = $thing->set_desc(\@desc);
\@desc = $thing->get_desc();
         $thing->add_desc($desc);

=head2 SEE ALSO

L<dbbase> L<dbfields> L<dbimages>

=cut

-- 
Fools ignore complexity. Pragmatists suffer it.
Some can avoid it. Geniuses remove it.



More information about the Canberra-pm mailing list