HACKING.pod - contributing to TAP::Harness
This is the guide for TAP::Harness internals contributors (developers, testers, documenters.)
If you are looking for more information on how to use TAP::Harness, you probably want the TAP::Harness::Cookbook instead.
See the resources section in META.yml (or Build.PL) for links to the project mailing list, bug tracker, svn repository, etc.
For best results, read the rest of this file, check RT for bugs which scratch your itch, join the mailing list, etc.
The project comes with a .perltidyrc, which perltidy will automatically use if the project root is your working directory. This is setup by default to read and write the perl code on a pipe. To configure your editor:
.perltidyrc
vim
In .vimrc, you can add the following lines:
.vimrc
nnoremap <Leader>pt :%!perltidy -q<cr> " only work in 'normal' mode vnoremap <Leader>pt :!perltidy -q<cr> " only work in 'visual' mode
In other words, if your Leader is a backslash, you can type \pt to reformat the file using the .perltidyrc. If you are in visual mode (selecting lines with shift-v), then only the code you have currently have selected will be reformattted.
Leader
\pt
emacs
For emacs, you can use this snippet from Sam Tregar (http://use.perl.org/~samtregar/journal/30185):
(defun perltidy-region () "Run perltidy on the current region." (interactive) (save-excursion (shell-command-on-region (point) (mark) "perltidy -q" nil t) (cperl-mode))) (defun perltidy-all () "Run perltidy on the current region." (interactive) (let ((p (point))) (save-excursion (shell-command-on-region (point-min) (point-max) "perltidy -q" nil t) ) (goto-char p) (cperl-mode))) (global-set-key "\M-t" `perltidy-region) (global-set-key "\M-T" `perltidy-all)
...
The end-user and API documentation is all in the 'lib/' directory. In .pm files, the pod is "inline" to the code. See perlpod for more about pod.
For compatibility's sake, we do not use the =head3 and =head4 commands.
=head1 SECTION
Sections begin with an =head1 command and are all-caps.
=head1
NAME VERSION SYNOPSIS CONSTRUCTOR METHODS CLASS METHODS SOME OTHER SORT OF METHODS SEE ALSO
=head2 method
The =head2 command documents a method. The name of the method should have no adornment (e.g. don't C>method> or C>method($list, $of, $params)>.)
=head2
These sections should begin with a short description of what the method does, followed by one or more examples of usage. If needed, elaborate on the subtleties of the parameters and context after (and/or between) the example(s).
=head2 this_method This method does some blah blah blah. my @answer = $thing->this_method(@arguments); =head2 that_thing Returns true if the thing is true. if($thing->that_thing) { ... }
=item parameter
Use =item commands for method arguments and parameters (and etc.) In most html pod formatters, these do not get added to the table-of-contents at the top of the page.
=item
Be careful of the wording of L<Some::Module>. Older pod formatters would render this as "the Some::Module manpage", so it is best to either word your links as "(see <Some::Module> for details.)" or use the "explicit rendering" form of "<Some::Module|Some::Module>".
L<Some::Module>
(see <Some::Module> for details.)
<Some::Module|Some::Module>
The version numbers are updated by Perl::Version.
The following "formats" are used with =begin/=end and =for commands for pod which is not part of the public end-user/API documentation.
=begin
=end
=for
Use this if you are uncertain about a change to some pod or think it needs work.
=head2 some_method ... =for note This is either falsely documented or a bug -- see ...
=begin developer Long-winded explanation of why some code is the way it is or various other subtleties which might incite head-scratching and WTF'ing. =end developer
=for deprecated removed in 0.09, kill by ~0.25
To install Test::Harness, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Harness
CPAN shell
perl -MCPAN -e shell install Test::Harness
For more information on module installation, please visit the detailed CPAN module installation guide.