Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 266 lines (169 sloc) 7.345 kB
968d404 @rcaputo Migrate proto-documentation from the wiki.
authored
1 Formerly http://poe.perl.org/action/edit?id=POE_Documentation/Style_Modules
2
3 ---
4
5 == Anatomy of a Man Page ==
6
7 These are the main <tt>=head1</tt> headings in most manpages.
8
9 === NAME ===
10
11 This section's body contains the module's class name, a hyphen, and a
12 one-line description for <CODE>man -k</CODE> or <CODE>apropos</CODE>.
13
14 =head1 NAME
15
16 Wibble - a wibble module used for wibbling widgets
17
18 === SYNOPSIS ===
19
20 This section's body contains example uses of the module. Nine times
21 out of ten, experienced users should be able to look at the SYNOPSIS
22 for a quick reminder of how something works.
23
24 =head1 SYNOPSIS
25
26 use Wibble;
27 my $wibble = Wibble-&gt;new();
28 $wibble-&gt;wobble($widget);
29
30 === DESCRIPTION ===
31
32 A module's DESCRIPTION describes the module in detail and explains how
33 it works. It provides background information on some of the module's
34 concepts, and explains its public interface.
35
36 =head1 DESCRIPTION
37
38 The Wibble module blah blah blah blah blah.
39
40 Here are some popular sub-heading within DESCRIPTION. They have been
41 cribbed from the perlfunc man page.
42
43 ==== Methods (or Functions) by Category ====
44
45 In a complex module like Kernel, it helps to group public methods into
46 related categories.
47
48 =head2 Methods by Category
49
50 =over 2
51
52 =item Methods for wobbling
53
54 C&lt;wobble_now&gt;, C&lt;wobble_later&gt;, C&lt;wobble_to_and_fro&gt;
55
56 =back
57
58 ==== Methods (or Functions) by Name ====
59
60 This is an alphabetical listing of each method (or function), its call
61 signature, and a description of how it works.
62
63 =head2 Alphabetical Listing of Wibble Functions
64
65 =over 2
66
67 =item wobble LIST
68
69 =item wobble
70
71 Mightily wobbles a list of widgets. Without a widget list, the
72 Wibble object wobbles itself.
73
74 See also the C&lt;wobble&gt; event.
75
76 =item ...
77
78 ...
79
80 =back
81
82 For POE, methods that can generate events should list the events they
83 generate, perhaps linking to them so that hyperlinked documentation
84 can take the reader there right away.
85
86 ==== Events by Category ====
87
88 Many POE modules can generate events, and some of the events can be
89 grouped into categories. This lists each category of events and the
90 events that can be found within.
91
92 =head2 Events by Category
93
94 =over 2
95
96 =item Job control events
97
98 Some sort of description of job control events goes here.
99
100 _child, _parent, _start, _stop
101
102 =back
103
104 ==== Events by Name ====
105
106 This is an alphabetical listing of each event the module can generate.
107 Where a particular class of events doesn't have a default name, the
108 class' name is used instead.
109
110 =head2 Alphabetical Listing of Wibble Events
111
112 =over 2
113
114 =item wobble
115
116 Tells a widget when it's been wobbled by a Wibble object. C&lt;wobble&gt;
117 events include no parameters.
118
119 =item immediate weeble events
120
121 Immediately tell a widget it's been weebled by a Wibble object.
122 These are not queued and dispatched later. They include one
123 parameter which describes how hard a widget has been weebled.
124
125 =back
126
127 === BUGS ===
128
129 Programs rarely are complete or perfect. The BUGS section lists known
130 gotchas and problems, regardless whether they're intended to be fixed
131 any time soon. Anything weird that's meant to be that way is a
132 feature and should be discussed in the DESCRIPTION instead.
133
134 =head1 BUGS
135
136 Wibbles wobble, but they don't fall down.
137
138 === DIAGNOSTICS ===
139
140 If the module contains things used for debugging it, and they're
141 intended to be used by other programmers, then they're documented
142 here.
143
144 =head1 DIAGNOSTICS
145
146 Wibble has a number of tracing and asserting routines which can be
147 enabled by making the following constants true.
148
149 =over 2
150
151 =item ASSERT_WIBBLE
152
153 Yatta-yatta-yatta.
154
155 =back
156
157 === AUTHORS ===
158
159 The module's authors, their contact addresses (e-mail and/or home
160 page), and their roles in creating the module.
161
162 =head1 AUTHORS
163
164 Arthur Bergman, primary author, <foo@foo.com>
165 Rocco Caputo, nitpicker, <foo@bar.com>
166 Matt Cashner, documentation, <foo@baz.com>
167 Richard Soderberg, lovely and talented assistant, <foo@quux.com>
168
169 === LICENSE ===
170
171 The module's copyright notice and license information go here. If the
172 module is maintained out of a revision control system, a copy of its
173 ID tag is also useful here.
174
175 $Id$
176
177 POE::Wibble is Copyright 2001 by Arthur Bergman. All rights are
178 reserved. You may distribute and/or modify it under the same terms
179 as perl itself.
180
181 Add-on modules which are written and maintained by others (such as
182 components) can have whatever license their authors decide are best.
183
184 POE core modules, however, must be distributed under the same terms as
185 Perl itself. This simplifies licensing issues for people using POE:
186 It's assumed they already have no problems with Perl's license.
187
188 === SEE ALSO ===
189
190 Hardly any POE module stands on its own. The SEE ALSO section points
191 readers to related modules where more information lies.
192
193 =head1 SEE ALSO
194
195 Wibble wobbles widgets. See L<Widget>; for more information about
196 widgets.
197
198 == Anatomy of a Method or Function Definitions ==
199
200 Functions should be defined using the same general format, which I'm
201 cribbing from perlfunc because everyone should be familiar with that.
202
203 The first sentence of the first paragraph summarizes the method or
204 function's purpose. The rest of the paragraph discusses different
205 call signatures and contexts, and the function's behavior in each.
206
207 The remainder of the description goes into detail about the different
208 ways a method or function can be called, in order from most common to
209 least common usage. Use lots of examples, preferrably ones that can
210 be lifted verbatim to do useful things.
211
212 See just about everything in perlfunc as an example.
213
214 == Test Messages ==
215
216 It is important that test messages be clear and consistent. A lot of
217 them indicate skipped tests, usually because some feature or module is
218 not present.
219
220 $^O does not support (feature) properly.
221 $^O does not support (feature).
222 Can't test (toolkit) without a DISPLAY. (Set one today, ok?)
223 Could not create a pipe in any form.
224 Module::Foo #.## or newer is needede for this/these tests.
225 Module::Foo and Module::Bar are needed for this/these tests.
226 Module::Foo is needed for this/these tests.
227 Module::Foo or Module::Bar is needed for this/these tests.
228 Module::Foo requires Module::Bar #.## or newer.
229 Module::Foo, Module::Bar, or Module::Baz is needed for this/these tests.
230
231 ***
232 *** Please note: This test will pop up a window.
233 ***
234
235 ***
236 *** Seconds between signal and first reap: (seconds)
237 *** Seconds to wait for other reaps: (seconds)
238 *** Seconds to wait after final reap: 5
239 ***
240
241 ***
242 *** Seconds to fork (count) children: (seconds)
243 *** Seconds to wait for system to settle: (seconds)
244 ***
245
246 Term::Cap did not find a valid termcap file.
247 This test crashes ActiveState Perl.
248
249 ***
250 *** This test tries to compensate for slow machines. It times its
251 *** first test and uses that as its timeout for subsequent tests.
252 *** This test may take a while on slow or resource-starved machines.
253 *** It may even fail if it incorrectly estimates its timeouts.
254 ***
255
256 Windows tests are not necessary on $^O.
257
258 == Version, Author & Copyright ==
259
260 $Id$
261
262
263 This style guide is copyright 2001-2002 by Rocco Caputo. All rights
264 reserved. This guide is free text and may be distributed and/or
265 modified under the same terms as Perl itself.
Something went wrong with that request. Please try again.