[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