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).



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.