Javadoc-style Perl Documentation Generator

I'm not a huge fan of Java, but I really do appreciate their standards for code comments. I use them in my PHP, C++, and Perl code. There is obviously some changing that needs to happen becuase those languages don't all comment the same, but for the most part it works really well.

Today I needed to write up a document on how one of my larger scripts/programs worked. I wanted to include the script architecture, but didn't have a good way to do it. Then I remembered something one of my favorite open source projects does. MediaWiki is doing continuous integration and so they use (as I know other OSS projects do) Jenkins to do post-commit validation. Specifically relating to this post, they use the Jenkins scripts to verify that the comments for each function are in the right format and contain the right data types, etc. In application to my project at hand, in my Perl scripts this would look something like...

The commit validation scripts Jenkins uses would check if the subroutine definition did in fact require two parameters and that the function returned boolean. Granted, since Perl isn't strongly typed, this has to be a bit looser than it would for other languages (C++, C#, etc), but you get the idea. This documentation style is still awesome (at least, I think it is)

What I needed today though was a script that parsed my other scripts, read in all the subroutines (Perl, remember?), parsed out the comments for each one, and returned HTML using inline styles so I could copy it into a Word (well, LibreOffice Writer) doc without losing formatting. That said, here's the quick and dirty.