1HACKING(3) User Contributed Perl Documentation HACKING(3)
2
6 HACKING.pod - contributing to TAP::Harness
7
9 This is the guide for TAP::Harness internals contributors (developers,
10 testers, documenters.)
11 If you are looking for more information on how to use TAP::Harness, you
13 probably want
14 <http://testanything.org/wiki/index.php/TAP::Parser_Cookbook> instead.
15
17 See the resources section in META.yml or Build.PL for links to the
18 project mailing list, bug tracker, svn repository, etc.
19 For ease of reference, at the time of writing the SVN repository was
21 at:
22 http://svn.hexten.net/tapx
24 To get the latest version of trunk:
26 git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git
28 For best results, read the rest of this file, check RT for bugs which
30 scratch your itch, join the mailing list, etc.
31
33 perltidy
34 The project comes with a ".perltidyrc", which perltidy will
35 automatically use if the project root is your working directory. This
36 is setup by default to read and write the perl code on a pipe. To
37 configure your editor:
38 · vim
40 In ".vimrc", you can add the following lines:
42 nnoremap <Leader>pt :%!perltidy -q<cr> " only work in 'normal' mode
44 vnoremap <Leader>pt :!perltidy -q<cr> " only work in 'visual' mode
45 In other words, if your "Leader" is a backslash, you can type "\pt"
47 to reformat the file using the ".perltidyrc". If you are in visual
48 mode (selecting lines with shift-v), then only the code you have
49 currently have selected will be reformatted.
50 · emacs
52 For emacs, you can use this snippet from Sam Tregar
54 (<http://use.perl.org/~samtregar/journal/30185>):
55 (defun perltidy-region ()
57 "Run perltidy on the current region."
58 (interactive)
59 (save-excursion
60 (shell-command-on-region (point) (mark) "perltidy -q" nil t)
61 (cperl-mode)))
62 (defun perltidy-all ()
64 "Run perltidy on the current region."
65 (interactive)
66 (let ((p (point)))
67 (save-excursion
68 (shell-command-on-region (point-min) (point-max) "perltidy -q" nil t)
69 )
70 (goto-char p)
71 (cperl-mode)))
72 (global-set-key "\M-t" `perltidy-region)
74 (global-set-key "\M-T" `perltidy-all)
75
77 ...
78
80 ...
81
83 TAP::Object is the common base class to all TAP::* modules, and should
84 be for any that you write.
85
87 Exceptions should be raised with Carp:
88 require Carp;
90 Carp::croak("Unsupported syntax version: $version");
91 require Carp;
93 Carp::confess("Unsupported syntax version: $version");
94
96 Any documented sub that needs to be changed or removed (and would
97 therefore cause a backwards-compat issue) must go through a deprecation
98 cycle to give developers a chance to adjust:
99 1. Document the deprecation
101 2. Carp a suitable message
102 3. Release
103 4. Change the code
104 5. Release
105
107 The end-user and API documentation is all in the 'lib/' directory. In
108 .pm files, the pod is "inline" to the code. See perlpod for more about
109 pod.
110 Pod Commands
112 For compatibility's sake, we do not use the =head3 and =head4 commands.
113 "=head1 SECTION"
115 Sections begin with an "=head1" command and are all-caps.
116 NAME
118 VERSION
119 SYNOPSIS
120 CONSTRUCTOR
121 METHODS
122 CLASS METHODS
123 SOME OTHER SORT OF METHODS
124 SEE ALSO
125 "=head2 method"
127 The "=head2" command documents a method. The name of the method
128 should have no adornment (e.g. don't C<method> or C<method($list,
129 $of, $params)>.)
130 These sections should begin with a short description of what the
132 method does, followed by one or more examples of usage. If needed,
133 elaborate on the subtleties of the parameters and context after
134 (and/or between) the example(s).
135 =head2 this_method
137 This method does some blah blah blah.
139 my @answer = $thing->this_method(@arguments);
141 =head2 that_thing
143 Returns true if the thing is true.
145 if($thing->that_thing) {
147 ...
148 }
149 "=item parameter"
151 Use "=item" commands for method arguments and parameters (and etc.)
152 In most html pod formatters, these do not get added to the table-
153 of-contents at the top of the page.
154 Pod Formatting Codes
156 L<Some::Module>
157 Be careful of the wording of "L<Some::Module>". Older pod
158 formatters would render this as "the Some::Module manpage", so it
159 is best to either word your links as ""(see <Some::Module> for
160 details.)"" or use the "explicit rendering" form of
161 ""<Some::Module|Some::Module>"".
162 VERSION
164 The version numbers are updated by Perl::Version.
165 DEVELOPER DOCS/NOTES
167 The following "formats" are used with "=begin"/"=end" and "=for"
168 commands for pod which is not part of the public end-user/API
169 documentation.
170 note
172 Use this if you are uncertain about a change to some pod or think
173 it needs work.
174 =head2 some_method
176 ...
178 =for note
180 This is either falsely documented or a bug -- see ...
181 developer
183 =begin developer
184 Long-winded explanation of why some code is the way it is or various
186 other subtleties which might incite head-scratching and WTF'ing.
187 =end developer
189 deprecated
191 =for deprecated
192 removed in 0.09, kill by ~0.25
193
195 If you have commit access, please bear this in mind.
196 Development is done either on trunk or a branch, as appropriate:
198 If it's something that might be controversial, break the build or take
200 a long time (more than a couple of weeks) to complete then it'd
201 probably be appropriate to branch. Otherwise it can go in trunk.
202 If in doubt discuss it on the mailing list before you commit.
204perl v5.16.3 2013-05-02 HACKING(3)