I’m a big believer in automated testing. Not just that your code performs the correct functions, but also that the code meets whatever ‘policy’ decisions you’ve chosen. So, for example, at work we can’t check in perl code in that hasn’t provided POD documentation all its public methods. This is achieved using the wonderful Pod::Coverage module.

But today, when trying to check some code in, I was warned that I hadn’t documented the methods ("" and (bool in a class!

A little digging revealed an interesting facet of Perl that I hadn’t previously been aware of. I was using Perl’s overloading ability, which lets you specify how an object should be treated in various contexts (in this case, when you try to stringify it or check it in a boolean context). This is a really useful ability, but I’ve never examined how it actually works before. It turns out that it does this, in part, by creating functions in your class that are named after the operation you’re overloading, prefixed with a bracket. (Beyond that it gets much scarier!)

So, when Pod::Coverage comes to do its checking (by digging through the symbol table for the class it’s examining to see what methods exist and should be documented) it discovers these strange methods and, finding no documentation, complains.

Until I see how Richard Clamp decides to work around this in Pod::Coverage I’m now faced with either providing a bizarre piece of documentation or adapting our
build script to not complain about this sort of error…