Table of Contents
These are the main =head1 headings in most manpages.
This section's body contains the module's class name, a hyphen, and a
one-line description for
man -k or
Wibble - a wibble module used for wibbling widgets
This section's body contains example uses of the module. Nine times out of ten, experienced users should be able to look at the SYNOPSIS for a quick reminder of how something works.
use Wibble; my $wibble = Wibble->new(); $wibble->wobble($widget);
A module's DESCRIPTION describes the module in detail and explains how it works. It provides background information on some of the module's concepts, and explains its public interface.
The Wibble module blah blah blah blah blah.
Here are some popular sub-heading within DESCRIPTION. They have been cribbed from the perlfunc man page.
In a complex module like Kernel, it helps to group public methods into related categories.
=head2 Methods by Category
=item Methods for wobbling
C<wobble_now>, C<wobble_later>, C<wobble_to_and_fro>
This is an alphabetical listing of each method (or function), its call signature, and a description of how it works.
=head2 Alphabetical Listing of Wibble Functions
=item wobble LIST
Mightily wobbles a list of widgets. Without a widget list, the Wibble object wobbles itself.
See also the C<wobble> event.
For POE, methods that can generate events should list the events they generate, perhaps linking to them so that hyperlinked documentation can take the reader there right away.
Many POE modules can generate events, and some of the events can be grouped into categories. This lists each category of events and the events that can be found within.
=head2 Events by Category
=item Job control events
Some sort of description of job control events goes here.
_child, _parent, _start, _stop
This is an alphabetical listing of each event the module can generate. Where a particular class of events doesn't have a default name, the class' name is used instead.
=head2 Alphabetical Listing of Wibble Events
Tells a widget when it's been wobbled by a Wibble object. C<wobble> events include no parameters.
=item immediate weeble events
Immediately tell a widget it's been weebled by a Wibble object. These are not queued and dispatched later. They include one parameter which describes how hard a widget has been weebled.
Programs rarely are complete or perfect. The BUGS section lists known gotchas and problems, regardless whether they're intended to be fixed any time soon. Anything weird that's meant to be that way is a feature and should be discussed in the DESCRIPTION instead.
Wibbles wobble, but they don't fall down.
If the module contains things used for debugging it, and they're intended to be used by other programmers, then they're documented here.
Wibble has a number of tracing and asserting routines which can be enabled by making the following constants true.
The module's authors, their contact addresses (e-mail and/or home page), and their roles in creating the module.
Arthur Bergman, primary author, <email@example.com> Rocco Caputo, nitpicker, <firstname.lastname@example.org> Matt Cashner, documentation, <email@example.com> Richard Soderberg, lovely and talented assistant, <firstname.lastname@example.org>
The module's copyright notice and license information go here. If the module is maintained out of a revision control system, a copy of its ID tag is also useful here.
POE::Wibble is Copyright 2001 by Arthur Bergman. All rights are reserved. You may distribute and/or modify it under the same terms as perl itself.
Add-on modules which are written and maintained by others (such as components) can have whatever license their authors decide are best.
POE core modules, however, must be distributed under the same terms as Perl itself. This simplifies licensing issues for people using POE: It's assumed they already have no problems with Perl's license.
Hardly any POE module stands on its own. The SEE ALSO section points readers to related modules where more information lies.
=head1 SEE ALSO
Wibble wobbles widgets. See L<Widget>; for more information about widgets.
Functions should be defined using the same general format, which I'm cribbing from perlfunc because everyone should be familiar with that.
The first sentence of the first paragraph summarizes the method or function's purpose. The rest of the paragraph discusses different call signatures and contexts, and the function's behavior in each.
The remainder of the description goes into detail about the different ways a method or function can be called, in order from most common to least common usage. Use lots of examples, preferrably ones that can be lifted verbatim to do useful things.
See just about everything in perlfunc as an example.
It is important that test messages be clear and consistent. A lot of them indicate skipped tests, usually because some feature or module is not present.
$^O does not support (feature) properly. $^O does not support (feature). Can't test (toolkit) without a DISPLAY. (Set one today, ok?) Could not create a pipe in any form. Module::Foo #.## or newer is needede for this/these tests. Module::Foo and Module::Bar are needed for this/these tests. Module::Foo is needed for this/these tests. Module::Foo or Module::Bar is needed for this/these tests. Module::Foo requires Module::Bar #.## or newer. Module::Foo, Module::Bar, or Module::Baz is needed for this/these tests.
*** *** Please note: This test will pop up a window. ***
*** *** Seconds between signal and first reap: (seconds) *** Seconds to wait for other reaps: (seconds) *** Seconds to wait after final reap: 5 ***
*** *** Seconds to fork (count) children: (seconds) *** Seconds to wait for system to settle: (seconds) ***
Term::Cap did not find a valid termcap file. This test crashes ActiveState Perl.
*** *** This test tries to compensate for slow machines. It times its *** first test and uses that as its timeout for subsequent tests. *** This test may take a while on slow or resource-starved machines. *** It may even fail if it incorrectly estimates its timeouts. ***
Windows tests are not necessary on $^O.
This style guide is copyright 2001-2002 by Rocco Caputo. All rights reserved. This guide is free text and may be distributed and/or modified under the same terms as Perl itself.