in reply to Crash Course in POD
Nobody reads pod in pod format.
Pod is best kept with the sourcecode, that way synchronization doesn't become a problem. If the pod is staring you in the face, at the same time as the sourcecode, it's hard to ignore mismatches ;)
Any stuff you put in external pod files (.pod) should be tutorial like material (extended documentation) ~ the api spec should be in with the module (.pm )
Aside from that, don't get fancy with the pod (avoid =begin exoticFormat , bah!). Keep it simple.
Here are a few modules with pod that I wrote ;)
HTML::LinkExtractor ~ a good pod example. I most like to read pod produced by Pod::Html, cause it makes a nice TOC at the top (like you can see there).
If you look at the source, you'll see that the pod is at the __END__. Since this was a very short module, it makes little difference, but for bigger modules, it will definetly be harder to manage __END__ pod, so you'll wanna use inline pod , like:
=head1 NAME
The name Is ~ And it does this in one line of desc
=head1 DESCRIPTION
You know.
See L<"new"> aka See L<the newest|"new">
=head1 SYNOPSIS
a short usage example (at least I like to keep it short)
use Foo::Bar;
my $foo = new Foo::Bar ( Foo => 'required' );
die $foo->Bar;
=head1 METHODS (or Functions ;))
A little blurb about the methods/functions or the overall
interface of the thingamajigger ;)
=cut
use strict;
...
=head2 C<new>
The constructor. The only class method. Takes 4 arguments.
=over 4
=item Foo
Required argument, cause Bar bar bar Baz!
...
=back
=cut
sub new {
...
}
...
1;
# the end of the code
# I try not to put an __END__ token here cause mod_perl
# generally doesn't like that
=head1 SEE ALSO
L<Foo::Bar::Tutorial>, L<perlpod|Pod::perlpod>, L<perlpodspec|Pod::perlpodspec>
=head1 LICENSE
This software is released under the same terms as perl itself.
If you don't know what that means visit http://perl.com/
=head1 AUTHOR
Copyright (c) A. U. Thor
All rights Reserved
=cut
Which when viewed through Pod::Html turns into:
The name Is ~ And it does this in one line of desc
You know. See new aka See the newest
a short usage example (at least I like to keep it short)
use Foo::Bar;
my $foo = new Foo::Bar ( Foo => 'required' );
die $foo->Bar;
A little blurb about the methods/functions or the overall interface of the thingamajigger ;)
The constructor. The only class method. Takes 4 arguments.
...
the Foo::Bar::Tutorial manpage, perlpod, perlpodspec
This software is released under the same terms as perl itself. If you don't know what that means visit http://perl.com/
Copyright (c) A. U. Thor All rights Reserved
Now that is gravy right there ;)(that's the way i'd lay it out). It is important to remember not to document methods that the user of your module should not be calling directly. Use #c#o#m#m#e#n#t#s# for those.
Pod::Stripper ~ a bad example, mostly cause they're test cases ;)(deep pod voodoo, cause perl's idea of pod is different ~ perlpod/perlsyn explains)
____________________________________________________
** The Third rule of perl club is a statement of fact: pod is sexy.
|
|---|
| Replies are listed 'Best First'. | |
|---|---|
|
Re^2: Crash Course in POD
by Aristotle (Chancellor) on Sep 25, 2002 at 15:50 UTC | |
by Abigail-II (Bishop) on Apr 23, 2003 at 09:20 UTC | |
by Aristotle (Chancellor) on Apr 23, 2003 at 13:19 UTC | |
by Juerd (Abbot) on Apr 23, 2003 at 09:22 UTC | |
by Aristotle (Chancellor) on Apr 23, 2003 at 13:39 UTC | |
by ctilmes (Vicar) on Apr 23, 2003 at 15:44 UTC | |
by Abigail-II (Bishop) on Apr 23, 2003 at 09:32 UTC | |
|
Re: Re: Crash Course in POD
by Juerd (Abbot) on Apr 23, 2003 at 08:43 UTC | |
by PodMaster (Abbot) on Apr 23, 2003 at 08:50 UTC | |
by Juerd (Abbot) on Apr 23, 2003 at 09:20 UTC | |
by IlyaM (Parson) on Apr 23, 2003 at 12:14 UTC | |
by Abigail-II (Bishop) on Apr 23, 2003 at 12:21 UTC | |
| |
by Juerd (Abbot) on Apr 23, 2003 at 13:57 UTC |