DOCS or GTFO

Ok, you hate documenting. But it's part of the deal.

As you may know, there are tools that generate browseable documentation provided you document your code in a proper way.

Perl is no exception, and you can convert POD documentation to html, formatted plain text, LaTeX, etc...

To ensure you documented (at least, put the boilerplate) every non private function in your code, there's a module called Pod::Coverage that checks for undocumented functions, parsing your code, parsing your pod, and doing the match, and the diff.

Once that we're at it, we can bundle the check as a test for our application, and, in fact, there's Test::Pod::Coverage, that is exactly what we're looking for.

Ok, let's write a minimal module (BankAccount will do), using the right tools for each job.

module-starter --module=BankAccount --author="Raimon Grau" --email=raimonster@gmail.com --builder="Module::Install"

This will generate all the boilerplate and the directory scaffold needed, and it will include (at least if you have both packages installed).

	package BankAccount;
	use Moose;
	=head1 NAME
	BankAccount - Demo code
	=head1 VERSION
	Version 0.01
	=cut
	our $VERSION = '0.01';
	=head1 SYNOPSIS
	Quick summary of what the module does.
	Perhaps a little code snippet.
	use BankAccount;
	my $foo = BankAccount->new();
	...
	=cut
	has 'balance' => (is =>'rw', isa =>'Int', default => 0);
	=head1 FUNCTIONS
	=head2 deposit
	=cut
	sub deposit {
	my ($self, $howMuch) = @_;
	$self->balance( $self->balance + $howMuch ) ;
	}
	sub withdraw {
	my ($self, $howMuch) = @_;
	if ($self->balance >= $howMuch) {
	$self->balance($self->balance - $howMuch);
	}
	else{
	confess 'Not enough money';
	}
	}
	=head1 AUTHOR
	Raimon Grau, C<< <raimonster at gmail.com> >>
	=head1 BUGS
	Please report any bugs or feature requests to C<bug-bankaccount at rt.cpan.org>, or through
	the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=BankAccount>. I will be notified, and then you'll
	automatically be notified of progress on your bug as I make changes.
	=head1 SUPPORT
	You can find documentation for this module with the perldoc command.
	perldoc BankAccount
	You can also look for information at:
	=over 4
	=item * RT: CPAN's request tracker
	L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=BankAccount>
	=item * AnnoCPAN: Annotated CPAN documentation
	L<http://annocpan.org/dist/BankAccount>
	=item * CPAN Ratings
	L<http://cpanratings.perl.org/d/BankAccount>
	=item * Search CPAN
	L<http://search.cpan.org/dist/BankAccount/>
	=back
	=head1 ACKNOWLEDGEMENTS
	=head1 COPYRIGHT & LICENSE
	Copyright 2010 Raimon Grau, all rights reserved.
	This program is free software; you can redistribute it and/or modify it
	under the same terms as Perl itself.
	=cut
	1; # End of BankAccount

view raw BankAccount.pm hosted with ❤ by GitHub

This code will fail the pod coverage test, because the method withdraw is not documented.

Well, we have a new tool in our toolbox, that makes sure at least every method has its associated POD documentation. The module won't force you to document subs starting with underscore (thank god for DWIM). There's also other modules that build on this, like the one RJBS explains here.